多少文件就足够了？

（对于将来的开发人员）多少技术文档就足够了？在小时编码和小时记录之间是否存在适当的比例？

Papadimoulis认为您应该

生成所需的文档数量最少，以促进更多的了解，

那是一个好的指导方针，还是我应该创建一些具体的东西？

某些走廊可用性测试如何？向不熟悉该项目的开发人员显示代码和文档。当您能够做到这一点而又没有在观看他们查看代码的过程中强烈要求解释某件事的冲动时，您就足够了。

完美无瑕的生活，加上纯粹的退休生活。
安托万·德·圣艾修伯里

我已经考虑了一段时间了。

我的结论是-这不是数量问题，而是质量和环境的问题。

例如，适当的项目结构会在注释之前打上注释，解释文件的位置（实现与内涵）

类似地，分类以澄清上下文胜过命名（Patient的Id-> Patient.Id）。

我相信DDD在良好的文档中有发言权-分类提供了上下文，上下文创建了边界，边界导致了有意的实现（这是属于此的地方，而不是它必须存在的地方）。

代码本身不足以被视为文档。在大多数情况下，问题不在于代码的工作是否被注释或未注释，而是驱动力（域逻辑）没有被注释。

我们有时会忘记谁是老板-如果代码更改，则域逻辑或推理不应该更改，但是，如果代码域逻辑或推理更改，则代码肯定会更改。

一致性也非常重要-如果不一致，约定本身就没有用。

设计模式不只是“好的实践”，而是开发人员应该理解的术语。告诉开发人员向工厂添加新类型比向方法（上下文和一致性弱或缺失）中添加新类型更好地理解。

努力的一半是熟悉。

附带一提，似乎偏爱大量文档的API也是非常领域和上下文敏感的。有时，复制功能不是邪恶的（同一件事，不同的上下文），应将其视为单独的。

在评论方面，指出推理背后的领域逻辑总是好事。

例如，您在医疗行业工作。在您的方法中，您将写入“ IsPatientSecure = true;”。

现在，任何体面的程序员都可以弄清楚该患者被标记为安全的。但为什么？这意味着什么？

在这种情况下，患者是被安全转移到异地医院的犯人。知道这一点，就更容易想象导致这一点的事件（也许还有需要发生的事情）。

也许这篇文章充其量似乎是哲学性的-但请记住，您正在写的是“推理”或“逻辑”，而不是代码。

我同意Papadimouslis的报价。源代码可以说明一切，但是代码无法告诉您它为什么存在，应如何使用以及代码的行为。

我不知道比率高。

我几乎没有文档就继承了数百行代码。我很难理解为什么编写代码。在找出编写代码的原因之后，我不得不弄清楚如何使用代码。在发现这一点之后，我必须理解行为的假设，以便我可以支持和维护代码。

仅凭经验，不要发表过多的评论，否则最终将不得不维护实际的代码和文档。当文档和代码不同步时，这是一场噩梦。

足以让您停止第二次猜测自己。

如果您在工作中的任何时候都觉得“嗯，也许我应该记录下来”，请继续进行。然后，如果您已经写了一些文档，而您却想“也许我应该再解释一下”，那就继续吧。

重复冲洗直到感觉消失。

我发现，像乔治·费尔班克斯（George Fairbanks）的书《Just Enough Software Architecture》中介绍的那样，以风险为导向的方法非常适合理解多少文档就足够了。您可以在他的网站上阅读介绍此概念的部分（第3章），但主要思想是：

• 将担心您对“系统理解”的事情表示为风险
• 优先考虑风险
• 减轻风险，直到您的团队认为项目风险已充分降低。在这种情况下，您可能会创建某种文档。

为了帮助您解决问题，以便您可以对风险进行优先级排序，我发现确定几个目标（称为成功阈值）很有帮助，这是团队认为“成功”项目必须达到的最低目标。从文档角度来看，示例ToS可能类似于“开发人员应该能够在初次使用框架的4小时内构建一个简单的插件”。

现在确定一些风险。使用您已经构建（或正在构建）的系统，您的团队最担心的是什么？将其作为风险声明。我喜欢SEI的条件后果风格，但还有其他。例子：

• 数据模型又大又复杂；开发人员可能不知道在给定情况下要使用哪些数据元素。
• 系统具有API连接限制以提高可靠性；开发人员可能会不小心超出连接限制。
• 插件通过几个顺序的步骤使用；开发人员可能不会考虑这些有序步骤来构建插件。

现在作为一个团队，优先考虑风险。多次投票非常有效。

缓解最重要的风险，并从识别开始重复执行，直到项目失败的风险（由成功阈值定义）在可承受的范围内。通常，这将意味着您会冒一些风险，即团队认为不是太大的问题。请记住，您可能不想减轻所有风险。针对上述最后风险的缓解策略的一个示例可能是创建一个教程。

尽可能少，但尽可能多

我不记得我第一次听到该消息的位置和时间，但这是许多应用程序的座右铭。

技术或应用程序越复杂，就需要越多的文档（显然），但是显然您不想浪费时间过大。

JohnFx的“走廊测试”很不错。但是要相信自己；您开发了代码，因此所有人应该对需要特别注意的元素以及对所有人都显而易见的元素有所了解。考虑一下您在开发代码时遇到的困难，您可能会知道另一个开发人员在查看您的代码时会看到什么。

忘掉花力气的编码和花力气的文档记录之间的任何关系。

我相信您不能将其置于确切的规则中。记录文档的原因是要以某种形式提供不容易从原始代码中收集的知识，以便其他人可以理解甚至维护所述原始代码。

因此，您可以判断目标受众是否足够的唯一方法就是询问目标受众。我相信“同行评审”流程非常擅长于预先进行此操作。请注意，要使您的同龄人了解您在说什么，并需要将其最小化，需要多少解释。

如果您以前从未做过，则无法估计需要多少工作，但是经过几次迭代，您会更好地了解需要多少工作。