注释风格
1.总述
一般使用 // 或 /* */,只要统一就好。
2.说明
// 或 /* */ 都可以,但 // 更 常用,要在如何注释及注释风格上确保统一。
文件注释
1.总述
在每一个文件开头加入版权、作者、时间等描述。
文件注释描述了该文件的内容,如果一个文件只声明,或实现,或测试了一个对象,并且这个对象已经在它的声明处进行了详细的注释,那么就没必要再加上文件注释,除此之外的其他文件都需要文件注释。
2.说明
法律公告和作者信息:
每个文件都应该包含许可证引用. 为项目选择合适的许可证版本(比如, Apache 2.0, BSD, LGPL, GPL)。
如果你对原始作者的文件做了重大修改,请考虑删除原作者信息。
3.文件内容
如果一个 .h 文件声明了多个概念, 则文件注释应当对文件的内容做一个大致的说明, 同时说明各概念之间的联系. 一个一到两行的文件注释就足够了, 对于每个概念的详细文档应当放在各个概念中, 而不是文件注释中。
不要在 .h 和 .cc 之间复制注释, 这样的注释偏离了注释的实际意义。