《代码整洁之道》读书笔记三

第四章讲的是注释,有一句话我很喜欢,说的是:"Comments Do Not Make Up for Bad Code."(注释不是对劣质代码的补救)。事实上好的代码即便没有注释也拥有良好的可读性,但恰当的注释会让代码变得更可读、可维护性更高。

注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。作者认为注释是一种失败,我们总无法找到不用注释就能表达自我的方法,所以总要有注释,这并不值得庆贺。写注释的常见动机之一是糟糕代码的存在。带有少量注释的整洁而有表达力的代码,要比带有大量注释的零碎而复杂的代码像样的多。与其花时间编写解释你搞出的糟糕的代码注释,不如花时间清洁那堆糟糕的代码。
PS:这段话看起来可能有些过激。我们确实可以通过好的编码习惯减少不必要的注释。不过现在自动生成文档的技术都是从代码的注释中提取的。如果是这种情况,上司肯定是要求你写完备的注释的。
 
好注释:
 1. 法律信息。有时,公司代码规范要求编写与法律有关的注释。例如版权和著作申明。
 2.提供信息的注释。   
// returen an instance of the Responder being tested
protected abstract Responder responderInstance();

 不过作者认为 将函数名 重新命名为 responderBeingTested 注释就是多余的。

 3.对意图的解释。 有时注释不仅提供了有关实现的有用信息,而且还提供了某个决定后面的意图。
 4.阐释。 有时注释把某种晦涩难明的参数或返回值的意义翻译为某种可读形式。也会是有用的。特别是参数或者返回值是某个标准库的一部分,或者你不能修改代码,那帮助阐释其含义的代码就会有用,例如:
assertTrue(bb.compareTo(ba)==1);//bb>aa
assertTrue(a.compareTo(b)==-1);//a<b

直接看方法可能不明确,但有注释就明白多了。我看这2,3,4都是一个意思。就是说明是干嘛的。

5.警示,告诉别人要注意这个方法之类的。

6.放大。有的代码可能看着有点多余,但编码者当时是有他自己的考虑,这个时候需要注释下这个代码的重要性。避免后面被优化掉。

原文地址:https://www.cnblogs.com/dongao/p/14139574.html