《编程匠艺》读书笔记之三

第五章 随篇注释

• 注释非常像意见，你可以随心所欲的做注释，但这仅仅是因为做注释并不意味着这些注释就是正确的。
• 注释可以将优秀的代码和糟糕的代码区分开，将粗糙复杂艰涩难懂的逻辑与清晰友好的算法区分开。但是我们不需要过分夸大注释的作用，如果你已经编写出真正优秀的代码，那么注释就像蛋糕上的糖衣。
• 好的注释是避免让人望而生畏代码的一种策略，注释本身并不能够让糟糕的代码变得好一些。
• 什么是代码注释？从语法的角度来看，注释就是编译器将忽略不计的原代码块；从语义的角度来看，注释是昏暗肮脏的小路和明亮通畅的大道之间的区别，你可以使用它来强调某个特殊的问题领域，或哟工作头文件的记录媒介。
• 注释的目标读者是人，而不是计算机，如果我们想要提高注释的质量，就必须了解并满足人们在阅读代码时所真正需要的。
• 代码注释不是你应该放在代码中的唯一文档。注释不是规范，不是设计文档，也不是API参考。注释是一种总是会物理的附在代码上的宝贵的文档形式，是一种内部的文档化机制。
• 注释的形式各种各样，从根本上说，编写注释是一个主观的问题。
• 学会只编写够用的注释，过犹不及，我们要重视质量，而不是数量。
• 阅读你的注释的人也会阅读你的代码，因此尽可能在代码本身中进行文档化，而不要编写大量的注释。要将你的代码语句看做是第一级的注释，并让代码自文档化。
• 编的好的代码实际上并不需要注释，因为每行代码都可以自我解释。我们应该把时间花在编写不需要大量注释支持的代码上。
  注释中应该有哪些东西：
• 解释为什么，而不是怎么样。你应该改为几种描述为什么有些东西要这样写，或者下一个语句块最终要起到什么作用。当我们维护一段代码时，解释这段代码为什么存在的理由很少发生变化，但是这段代码的实现其目的的方法却很容易发生变化。
• 不要描述代码。无价值的描述性注释有时很明显，没有必要用英语费力的重复叙述代码，除非你要文档化一个相当复杂的没有注释就无法理解的算法。
• 不要取代代码。当你发现自己在编写密密麻麻的注释来解释你的代码时，赶快停下来，想一想是不是有一个更大的问题需要解决。
• 确保注释有用。好的注释犹如好的代码；它有如下特点：1. 记录意想不到的内容；2. 讲真话；3. 有价值；4. 清晰明了；3. 容易理解。
• 避免分心。注释的作用是说明周围的代码，因此我们必须避免所有干扰这个作用的因素。注释应当只是增加价值。需要避免以下形式的注释：1. 过去的事情；2. 你不想要的代码，不要把需要剔除的代码包含在注释中；3. ASCII技术；4. 代码块的结尾，应该与开头一起先是在同一页中，而且代码的版面应该是块的开头和结尾都一目了然。
• 不要文档化差劲的代码——重写这些代码。
  
  
  
  良好的注释应该有些原则是可以参考的，如下：
• 一致性。所有的注释都应该清晰明了，前后一致。为你的注释选择一种特定的布局方式，并且始终坚持使用这种方式。
• 清晰的块注释。要充分考虑到你的注释可能会被看到的环境，不要太沉迷于具有高亮显示的编辑器中。清晰的注释应该让文字上下对齐，使得在打印后也可以易于阅读。
• 缩进的注释。注释不应该截断代码，或者打乱逻辑流程。让注释的缩进位置和周围的代码保持一致。
• 行尾注释。在注视和代码之间保留空白是一种好习惯。
• 帮助你阅读代码。通常注释在它描述的代码的上方，而不是下方。
• 选择一种维护成本较低的风格。在美观的源代码和维护成本之间，总是存在一种平衡，与得到丑陋的代码相比，我更倾向于在维护上花一些时间。
• 分隔板。如果你的函数太大，以至于你需要一些视觉上的线索来提示函数的开头和结尾，那么你应当修改你的代码。
• 标志。注释还可以用作代码中内嵌的标志。
• 文件头注释。所有的源文件都应该一描述其内容的注释块作为开头，其中应该包含的信息是文件的目的和描述所有权及版权信息的版权声明。头注释中不应该包含容易过时的信息，也不需要包含描述每次都做了哪些修改的源文件历史记录。
  编写注释的两种方式：
• 首先用注释构造代码的结构，然后在各行注释下面填写代码。
• 首先徒手编写新的代码，然后添加必要的注释。
• 有经验的程序员会编写代码边写注释。实践会告诉你使用多少注释是正确的。
• 在错误得到修正的地方放置一个通告是一种常见的但是存在争议的注释习惯。在作出不明显的修改时是否应该添加注释，以防止别人在日后修改代码时又引入新的错误，对这个问题仍然存在着争论。
• 注释会过时的，所有粗心维护的代码都会过时，从而招致很多难看的缺陷，并且失去原本整洁的设计。注释过时的速度似乎比任何其他代码过时的速度都要快，他们会随着他们所描述的代码一起过时。
• 当你修正、添加或者修改任何代码时，修正、添加或修改周围的相关注释。我们必须让注释足够简单以便于更新，否则它们很容易过时。
• 如果你发现一段注释确实不正确或有误导作用，那么你应当把修改这段注释作为你的代码维护工作的一部分。
• 注释不会比它们所标注的代码更重要——你无法使用注释把糟糕的代码变好，你的目标应该是编写根本无需注释的自文档化的代码。
• 优秀的程序员：1. 尽量只写少量的好注释；2. 编写解释为什么的注释；3. 集中精力编写优秀的代码，而不是过多的注释；4. 编写有意义。有帮助的注释。
• 糟糕的程序员：1. 不能说出好的注释和差的注释之间的差异；2. 编写解释如何做的注释；3. 并不介意注释只是对他们自己有意义；4. 使用许多注释来支持糟糕的代码；5. 用多余的信息来填充源文件。