5.2.2 注释的风格（2）
3. 固定格式的注释
以标准格式编写可以被外部文档生成器解析的注释是一种日益流行的编程(www.cppentry.com)方法。在Java语言中，程序员可以用标准格式编写注释，从而允许名为JavaDoc的工具自动为项目创建超文本文档。对于C++(www.cppentry.com)而言，名为Doxygen(www.doxygen.org)的免费工具可以解析注释，从而自动生成HTML文档、类图、UNIX man pages以及其他有用的文档。Doxygen甚至可以辨别并解析C++(www.cppentry.com)程序中JavaDoc格式的注释。下面的代码给出了可以被Doxygen识别的JavaDoc格式的注释。
- /**
- * Implements the basic functionality of a watermelon
- * TODO: Implement updated algorithms!
- */
- class Watermelon
- {
- public:
- /**
- * @param initialSeeds The starting number of seeds
- */
- Watermelon(int initialSeeds);
- /**
- * Computes the seed ratio, using the Marigold algorithm.
- * @param slowCalc Whether or not to use long (slow) calculations
- * @return The marigold ratio
- */
- double calcSeedRatio(bool slowCalc);
- };
Doxygen可以识别C++(www.cppentry.com)语法以及特定的注释指令，例如@param以及@return，并生成定制的输出。图5-1给出了Doxygen生成的HTML类引用示例。
自动生成与图5-1类似的文档在开发时很有用，因为这些文档允许开发人员浏览类以及类之间关系的高层描述。您的团队可以方便地定制类似于Doxygen的工具来处理所采用的注释格式。理想情况下，您的团队应该专门布置一台计算机来编写日常文档。
 |
| 图 5-1 |
4. 特殊注释
通常您会根据需要编写注释，在此有一些在代码内使用注释的指导方针。
尽量避免使用无礼的或者令人反感的语言，因为您不知道将来谁会查看您的代码。
开一些内部的玩笑通常没有问题，但是应该让经理检查是否合适。
在可能的情况下，给出bug编号或者功能ID。
如果认为某个人在将来可能会与您讨论这些注释，给出您的姓名缩写以及日期。
不要为了避免承担责任而加入其他人的姓名缩写以及日期，否则您会被解雇。
当更新代码的时候记得更新注释。如果代码的文档中充斥着错误信息，会让人感动非常困惑。
如果您使用注释将某个函数分为多节，考虑这个函数是否能够分解为多个更小的函数。
5. 自文档化代码
编写良好的代码并非总是需要充裕的注释，最优秀的代码本身就容易阅读。如果您发现在每行都加入了注释，考虑是否可以重写这些代码以更好地配合注释中所讲的内容。记住C++(www.cppentry.com)是一门语言，其主要目的是告诉计算机做什么，但是语言的语义也可以向读者解释自身的含义。
编写自文档化(Self-documenting)代码的另一种方法是将代码分解(decompose)为小段。后面将详细介绍分解。
良好的代码本身就容易阅读，注释只需要提供有用的附加信息。