Language agnostic 项目前文件

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

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

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

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

实现二进制文件读取器

实现二进制文件编写器

创建对象以将表达式的数据封装到调用方

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

所以我的问题是：

---

我认为最好的文档是代码本身，这是对的吗。我们都同意需要一个高级别的概述。这个应该有多高？你的设计是为了陈述、类还是概念？什么对你有用？

我强烈建议你阅读《代码完成2》，以获得对这类问题的深刻见解

---

最后，我发现有几种方法可以实现这一点，从思维导图到概念图，甚至UML/伪代码。最后，对个人最有效的东西似乎就是要使用的东西。

我认为你想要的是一个软件需求规范

用一种混乱的方式编码所有的东西是一种错误的工作模式！ 您需要的是创建一个功能/非功能需求列表，以创建与UI需求和业务参与者创建用例的链接/相关/子/父关系

在这一步之后，您最终需要管理UML或SPEUDO代码中的所有设计接口，但是当您将需求（对于小项目）形式化时，就不再需要UML了

对于代码的文档，您可以使用doxygen或javadoc方法，简而言之， 你在代码中插入注释，然后用一个软件将所有文档以HTML/PDF的形式删除

通过这种方式，您可以按顺序接触到以下内容：

1-软件要求
现在，您已经全面了解了您的软件是什么，以及您的软件需要哪些功能，以及哪些约束条件（技术/非技术/时间/业务）。 以及在开发生命周期的最后阶段测试软件的用户案例

2-UML或伪代码
这是一种将您的工作分配给其他同事的简单方法，以及代码界面设计的简单代码概述

3-为其他像你这样的程序员提供的库文档以及所有的好处，不要浪费太多的匹配时间，在项目结束时写下所有的文档

我的2美分

谷歌关键词：

---

软件工程doxygen软件开发生命周期、CMMI、IEEE SRS（软件需求规范）。

我已经了解了，并且已经从头到尾阅读了。我发现除了伪代码之外，它仍然不能处理这个问题。就编码结构而言，它是一个非常宝贵的资源，但我不认为它回答了我的设计问题，即在规范中哪些是有效的，哪些是无效的。“我认为最好的文档是代码本身，这是正确的吗？”是的，我和其他程序员认为这是一个不幸的妥协。谢谢！）重读我对这个问题忘记的答案，让我感觉自己是一名专业的软件工程师；）英雄联盟