您应该记录全部还是大部分？

关于所有内容的记录似乎有点争议，包括字段的getter和setter的“ JavaBean”语法：人们说它的DRY不必要地冗长而重复，打破了DRY（不要重复自己），命名约定应该解释一切，并且会使代码/文档混乱。有时这些论点起作用。但有时，您最终会遇到以下情况：

上面大胆遵循这些原则的开源项目很常见。您剩下的都是完全没用的文档。但这并不能解释下面的情况，可能的影响，甚至是预期的值（是null还是永不null？我不知道； Javadoc不会告诉我）。

那我什么时候应该记录？即使偶尔会使代码混乱，我是否也要记录所有内容？还是我没有记录任何东西，因为在我看来这是“显而易见的”？

记录一切对记录有意义的内容。

是的，在理想的世界中，您将记录所有内容。但是，在地球上，我们每天只有24小时，一年只有365天有截止日期，功能削减，家人和朋友来访，休假。只是没有足够的时间来记录所有内容。因此，最好记录所有可能的事情（您不会完成），但可以通过以下方式最大程度地赚钱：

• 使代码可读性和方法签名尽可能明显，以便不太可能需要记录文档。
• 首先记录最晦涩的事物。记录下为使事情发散而必须执行的疯狂骇客行为，以帮助他人。
• 在做什么之前先记录原因 -不要评论做什么，例如“对余额小于零且评分小于1的客户记录进行迭代，并将其添加到exemptCustomers列表中”。记录为什么要使用纯英语（或您团队的语言）将其添加到列表中，例如“由于这些客户的余额为负数且评分较低，它们使我们蒙受了损失，因此请他们退出结算。

保持记录，直到您可以看到别人阅读它而无需解释任何内容。

在过去的一周有一个很大的，在The Daily WTF上一篇有关文档文章。我认为这说明了一切，因此我将保留链接：

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

基本上，它说如果您没有用的东西，您就不应该记录在案（一些文件只留在抽屉里腐烂了），并且记录了理解项目的某些部分所需的最少信息。太多的文档只会使读者感到困惑。

真正取决于代码对读者的可读性。找出谁是阅读代码的受众，并请符合要求的人阅读您的代码。

另一种方法是一周后检查您自己的代码，看看您是否仍然了解自己的工作，如果不了解，请记录下来并在两周左右的时间内检查代码。

尽管我很欣赏清晰而丰富的文档，但没有什么比自文档代码更合适了。因此，（对我而言）底线是：

非常怀疑（源代码）文档；尝试通过改进代码来使其冗余，但在必要时不要回避清晰，完整地记录文档。

当然，在某些情况下，出于“解释代码的作用”之外的原因（例如：庞大的团队基础，组织标准等），可能需要文档。

我对文档的建议是，如果代码中有任何花哨的内容，则应属于最新文档。花哨的东西有很多解释，在我看来，是以某种特殊方式完成的事情可能会引起副作用，例如，可以递归地完成某些事情，以确保孙子项在通过节点树时得到处理对所有后代进行一些测试。阐明为什么要以某种特定方式完成某件事可能是了解是否有充分理由使用某件事的好方法。

简而言之，文档可以帮助现在的开发人员以及将来的维护人员。

如果您还记得那条简单的格言，那么文档的级别应该是自定义的。

就文档而言，文档是浪费时间……但是今天解释您的工作要比五年后对代码进行逆向工程的人更有帮助。

我个人认为 考虑考虑记录所有内容。即在编码时，我会随时考虑文档是否会增加价值。大多数时候，对于原始问题中提到的各种约束和领域知识，答案都是肯定的。例如，可空性，独特的约束条件，更广泛领域中的领域解释。

为了避免重复，我倾向于使用此类信息大量记录主要API类。然后，仅记录行为不明显或不一致的实现和内部。我发现这很好用，因为需要最大帮助和文档的是API用户，通常可以放心地认为修改实现的人都知道API，因此知道这一点。

我也倾向于记录吸气剂。我不会将文档复制到setter，字段定义和构造函数参数上。我仅记录非显而易见的行为，例如这些地方的默认行为。可以从getter文档中推断出的任何行为均未记录。例如，如果将getter记录为永不返回null，除非没有默认设置，否则我通常不会记录不能将null传递给setter。

有些人喜欢在考虑文档但认为没有必要的地方添加空注释来标记“考虑文档”的行为。我不喜欢这种做法，因为它只会使代码混乱并妨碍您的操作。