language-agnostic - 项目前文档

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改善这个问题吗？更新问题，以便可以通过 editing this post 用事实和引文回答问题.

3年前关闭。




Improve this question




我有一个问题，我觉得很多程序员都可能涉及到...

我曾参与过许多小型项目。在我最初的论文头脑 Storm 之后，我倾向于开始编码。我想出的通常是实际应用程序的粗略工作模型。我以断开连接的方式设计，所以我谈论的是底层代码库，用户界面是最后一件事，因为库通常决定了 UI 中需要什么。随着我的项目越来越大，我担心我的“规范”或设计文档也应该如此。

根据我的调查，上面的段落以一种或另一种方式在整个互联网上得到了回应。当涉及 UI 时，有更多信息，但它是特定于 UI 的，与代码库无关。我开始意识到，也许代码就是代码就是代码。从我的广泛研究来看，设计文档和代码之间似乎没有 1:1 的映射。

当我需要研究一个主题时，我将信息转储到 OneNote 中，然后我将功能优先级划分为版本，然后划分为相关块，以便开发以相当线性的方式运行，我的任务往往如下所示:

实现二进制文件阅读器

实现二进制文件编写器

创建对象封装数据表达给调用者

现在，任何称职的程序员都知道，在这三个待办事项之间可能是一个潜在的代码墙，可以扩展到多个文件。我试图为每个任务绘制完整的代码流程，但我认为它不能有效地完成。当人们破坏伪代码时，它本质上还是代码，因此时间投资被否定了。

所以我的问题是:

我是否正确地假设最好的文档是代码本身。我们都同意需要一个高层次的概述。这应该有多高？您是按照声明、类或概念级别进行设计的吗？什么对你有用？

Answer 1

我强烈建议您阅读 Code Complete 2 以深入了解此类问题。

http://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670