C++程序设计：原理与实践（基础篇）（原书第2版）

7.6.4　注释

我们在编写计算器程序的过程中加入了一些注释。好的注释是程序代码的重要组成部分。在程序开发进度很紧时，我们往往会忽略注释。当我们回过头来进行代码清理的时候，是一个很好的时机来全面检查程序的每个部分，检查原来所写的注释是否满足以下要求：

1.在改动了程序代码以后，原来的注释是否仍然有效？

2.对读者来说注释是否充分？（通常是不够充分的。）

3.是否简短清晰，不至于分散读者看代码的注意力？

强调一下最后一条：最好的注释就是让程序本身来表达。如果读者了解程序设计语言，对一些意义已经很明确的代码，就应该避免不必要的冗长注释。例如：

你可能会在本书中发现一些类似的注释，但只限于用来解释你所不熟悉的语言特性的用法。

注释一般用于代码本身很难表达思想的情况。换句话说，代码说明它做了什么，但没有表达出它做这些的目的是什么（参见5.9.1节）。回顾一下计算器程序，其中就缺少一些必要的注释：函数本身说明了我们是如何处理表达式和单词的，但没有给出表达式和单词的具体含义。对于计算器程序，表达式的文法最适合放入代码注释或者说明文档中，以此解释表达式和单词的含义。

我们这里使用了块注释，它以/*开头，一直到*/结束。注释的开始是程序的版本变化历史，在实际程序中，版本历史一般用于记录每个版本相对于上个版本做了哪些修正和改进。 ...