代码文档优先？[关闭]

有没有人尝试过在实际编写代码之前先创建完整的代码文档？我早些时候就在考虑这个问题，因为我认为这将有助于编写具体的接口，并通过让您考虑类的交互方式来确保您的初始设计不会落空。这是一个好主意吗？有人尝试过吗？厄尔

是。

它使您思考代码应该执行的操作。 这个想法是，您可以从代码的任何部分开始，并且确切地知道完成该模块需要做什么。

与在IDE中相比，在绘图板上修复某些内容也更容易。

有两种思考方式：

1）与Word文档，Wiki等中的文档相同。根据定义，您没有完整的代码文档，因为您没有要编写的代码。您可以先尝试记录高级设计，假设，接口和合同。

2）作为可执行测试的文档。有一种观点认为可执行单元测试是最好的文档。这种思想流派在编写代码（TDD）之前也提倡此类文档。同时，您从一开始就没有针对整个系统编写所有测试。首先按用例细分，然后针对每个用例进行测试和编写代码。

从文档开始是经典的瀑布模型，并且具有与该模型相关的所有陷阱。概括地说，您记录的文档越多，当需求发生变化时就必须更新的内容越多。从用户文档开始的一个好处是您可能会更快地获得反馈（并因此获得更改）。但是经验表明，大多数人都不擅长将文档映射到操作。因此，我们改用原型，使人们可以实际使用该软件并以这种方式给出反馈。

“文档优先”的一种变体是文学编程。首先从程序员的角度写程序的功能描述。不断对其进行调整，直到编译为止。Voila，一个识字程序。

我个人发现使用图（例如UML）进行简单建模以显示事物的流程会更好。这比用文字记录事情要快得多，而且如果做得正确，也可以像描述一样。我会犹豫是否要进行“完全文档编制”，因为因为我个人从未有过我从事过的项目，并且在编程过程中并没有改变。

编辑：虽然应该花一些时间做一些文档。这使以后完成完整的文档变得更容易。

约书亚·布洛赫（Joshua Bloch）在他的《编码员在工作》一书中采访了这一点。

与更多的正统和学术观点相反，他建议一些与您的想法有关的东西（也许您已经在那儿阅读了？）：在编写文档之前，您必须了解您想要从系统中获得什么，并获得更“真实的”信息。的感觉。为此，他将设计部分接口和一些使用它们的客户端代码。

最重要的是要知道您要构建的内容：您要解决的问题。需求分析的重要性不可高估。有些人认为，“哦，是的，需求分析；您去拜访客户时说：“您需要什么？” 他告诉你，你完成了。”

没有东西会离事实很远。这不仅是谈判，而且是理解的过程。许多客户不会告诉您问题。他们会告诉您解决方案。例如，客户可能会说：“我需要您为该系统添加以下17个属性的支持。然后，您必须问：“为什么？您将如何处理系统？您期望它如何发展？'”等等。您来回走动，直到您弄清楚所有客户真正需要软件做什么。这些是用例。

在此阶段，最重要的事情是提出一套好用例。一旦有了这些，便有了一个基准，可以用来衡量任何可能的解决方案。如果您花费大量时间使它合理地接近正确就可以了，因为如果您错误地认为它已经死了。其余的过程将是徒劳的。

您能做的最糟糕的事情（我已经看到这种情况发生了）是，让一群聪明的人进入一个房间工作六个月，并在他们真正了解它们之前写了247页的系统规范试图建立。因为六个月后，他们将拥有一个非常精确的指定系统，这可能毫无用处。他们常常说：“我们在规范方面投入了很多资金，因此我们必须构建它。” 因此他们建立了无用的系统，并且永远都不会被使用。那太可怕了。如果没有用例，则构建该东西，然后尝试做一些非常简单的事情，就会意识到，“哦，我的天哪，做一些非常简单的事情，例如获取XML文档并打印它，需要一页又一页的样板。码。” 这是一件可怕的事情。

-约书亚·布洛赫（Joshua Bloch），来自彼得·塞贝尔（Peter Seibel）在“ 工作中的编码员：对编程技巧的思考 ”中的一次采访

如果您已经按照这些思路进行了思考，那么最好能掌握这本书并阅读整个访谈内容。正如我所说，他总是很有启发性。

有些人甚至走得更远，说公司应该完全倒退，所以

1. 撰写新闻稿
2. 写一个常见问题
3. 定义客户体验
4. 编写用户手册
5. 开始编程

参见 http://www.allthingsdistributed.com/2006/11/working_backwards.html

首先编写完整的代码文档可能有点过头，并且让人联想到瀑布方法。但是，我发现一种更实用的方法是首先编写README。原因如下：

自述文件并未记录您项目的每个细节。相反，它通常包含以下信息：

1. 描述：简短的“销售推销”。告诉读者为什么他们应该继续阅读。
2. 快速示例：支持说明的简短代码段或屏幕截图。
3. 快速入门：操作方法，安装说明以及更多示例。
4. 进一步的文档：链接到完整的文档和更多信息。
5. 项目组织：作者是谁，如何做出贡献，如何提交错误。
6. 法律声明：许可，版权和任何其他法律详细信息。

在最前面写“销售推销”迫使我清楚地知道为什么这个项目应该存在以及开发者为什么要使用它。仅仅写完整的句子来描述项目的行为通常会使它变得更好：您更好地理解它，提出新的想法并发现潜在的问题。这也是一个很好的优先排序工具：“销售”中的任何内容都是必须的！

“快速示例”和“快速入门指南”迫使我从用户的角度思考关键用例。我发现在编写任何代码之前进行此操作-在陷入实现细节和紧迫的期限之前-会导致API和设计更加简洁。请记住：应该编写程序供人们阅读，而只能偶然地使机器执行（SICP）。

在“更多文档”中，我创建了一些片段的概述，这些片段需要详细的文档，稍后再做。“项目组织”让我弄清楚谁将负责项目和编码实践。“法律声明” ...好吧，也可以将它们排除在外。

一旦有了基本的自述文件，便有了一个文档，该文档对于讨论，设计审查，分工和项目计划很有用。在您处理项目时，请经常与自述文件一起查看，以确保您仍处于正常状态。另外，随着您的进行，逐步更新自述文件和“更多文档”意味着您的所有文档都将在代码完成后完成，这比在最后一刻匆匆记录所有文档要愉快得多。

有关更多信息，请查看以下内容：

1. 自述驱动开发
2. 最重要的代码不是代码
3. 你就是你的文件

您为什么不考虑类如何交互？为什么这是一件坏事？实际上，我什至在不知道类是什么之前就考虑了交互作用。这样一来，班级就可以确定自己的身份。

在编写代码之前，您应该对打算做的事情有所了解。问题始终是如何使编码内容与编写的内容保持同步？一些人说不要尝试，其他人说忘记最初的文档并保持评论。当然，代码始终是规范的源代码。然后，问题就变成了值得为后来的人或使用该代码的人记录该代码的工作是否值得。任何人都可以弄清楚函数的作用。作家的工作是帮助某人在5分钟内理解任何人在一小时内能发现的东西。累加增量并确定路径。