《Google的C++编码规范》阅读随笔 —— 第六章 代码注释

注释是为别人而写的。

1.注释风格
使用//或者/* */,统一就好
//更加广泛，在如何注释和注释风格上确保统一

2.文件注释
在每一个文件开头加入版权公告，然后是文件内容描述。

法律公告和作者信息：
每一文件包含以下项，依次是：
1）版权：如Copyright 2008 GoogleInc.
2）许可版权：为项目选择合适的许可证版本，如Apache 2.0, BSD, LGPL, GPL;
3）作者：标识文件的原始作者
如果你对其他人创建的文件作了重大修改，将你的信息添加到作者信息里，这样当其他人对该文件有疑问时可以知道联系谁。

文件内容：
每一个文件版权许可及作者信息后，都要对文件内容进行注释说明。

通常，h文件要对所声明的类的功能和用法做简单说明，c文件包含了更多实现细节或算法讨论，如果你感觉这些实现细节对阅读有帮助，你可以吧c中的注释放到h中，并在c中指出文档在h中
不要在c和h中单纯的复制注释，没有意义

3.类注释：
每个类的定义都要附着描述类的功能和用法的注释。
// 描述甚至可以代码片段举例说明
class Name{...};
如果类有任何同步前提，文档说明之。如果该类的实例可被多线程访问，使用时务必注意文档说明

4.函数注释
函数声明处描述函数功能，定义处描述函数实现
函数声明：
注释于声明之前，描述函数功能及用法，注释使用描述式，而非指令式。内容有：
1）inouts和outputs
2）对于类成员函数而言：函数调用期间对象是否需要保持引用参数，是否会释放这些参数
3）如果分配了空间，需要由调用者释放
4）参数是否可以为NULL、
5）是否存在函数使用的性能隐忧
6）如果函数是可以重入的，其同步前提是什么？
但不要有冗余或者显而易见的注释

构造和析构函数需说明函数对参数做了什么。没有可以省略

函数定义：
说明函数功能和实现要点，实现的简要步骤、原由等
重点放在如何实现上

5.变量注释
好的变量名足以说明变量用途，特定情况下，需要额外注释说明

类数据成员：
注释说明用途，如果变量可以接受NULL或-1等警戒值，须说明之。

全局变量或者常量：
说明含义及用途

6.实现注释
代码实现中巧妙地、晦涩的、有趣的重要的地方可以加注释说明
出彩的或者复杂代码块之前加注释
比较晦涩的地方再行尾加注释，可以再代码之后空两格加注释

向函数传入，布尔值或者整数时，注释说明含义。如函数调用说明参数含义

7.标点、拼写和语法
写得好的注释要比差的要易读得多

8. TODO注释
   对于那些临时的、短期的解决方案，或已经够好但并不完美的代码使用TODO注释
   使用全大写细目TODO，后面括号里加上你的大名，邮件地址等，还可以加上冒号，方便查找

总结：
1）注释风格：C++更喜欢行注释
2）对于chinese coders来说，英文还是中文无所谓
3）注释也需要适当的缩进，首字母大写