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