幽默:好的代码本身就是最好的文档 - CodeWisdom

21-02-13 banq

好的代码本身就是最好的文档。在您要添加注释文档时,问问自己:“如何改进代码,以便不需要这些注释文档?” 改进代码,然后对其进行记录以使其更加清晰。 - Steve McConnell

 

众说纷纭:

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

 

 

1
猜你喜欢