好的代码本身就是最好的文档。在您要添加注释文档时，问问自己：“如何改进代码，以便不需要这些注释文档？” 改进代码，然后对其进行记录以使其更加清晰。 - Steve McConnell
众说纷纭：
我猜这家伙也没有写测试
代码格式化也起着快速理解和编辑将来的作用。
文档注释掩盖了错误的代码
大多数需要加入注释文档都表明您应该重构这些代码块。除非描述函数，类或其他文档字符串，否则请问自己：我可以使这种复杂的控制流程或陷阱变得更容易吗？
如果您在谈论技术文档，那么可以这样做。但是功能文档还是需要的，能了解如何使用应用程序/功能
文档注释最好是解释“为什么”而不是“什么”。代码在做什么，应该是显而易见的。为什么必须编写该代码有时可以从注释文档形式的一些解释中受益。（banq注：文档解释代码所在的上下文，但是这些上下文也是可以从其他代码中了解，如果你的代码是依据有界上下文划分，那么上下文还是可以依据代码自己来解释。）
好的代码总是可以自我解释。添加文档可以反映其有用性，而不是对其进行翻译。
|
