Google C++ 编程风格指南：注释

注释虽然写起来很痛苦, 但对保证代码可读性至关重要. 下面的规则描述了如何注释以及在哪儿注释. 当然也要记住: 注释固然很重要, 但最好的代码本身应该是自文档化. 有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字. 你写的注释是给代码读者看的: 下一个需要理解你的代码的人. 慷慨些吧, 下一个人可能就是你! 7.1. 注释风格 使用 // 或 /* */, 统一就好.   // 或 /* */ 都可以; 但 // 更 常用. 要在如何注释及注释风格上确保统一. 7.2. 文件注释 在每一个文件开头加入版权公告, 然后是文件内容描述.   法律公告和作者信息: 每个文件都应该包含以下项, 依次是:   版权声明 (比如, Copyright 2008 Google Inc.) 许可证. 为项目选择合适的许可证版本 (比如, Apache 2.0, BSD, LGPL, GPL) 作者: 标识文件的原始作者.   如果你对原始作者的文件做了重大修改, 将你的信息添加到作者信息里. 这样当其他人对该文件有疑问时可以知道该联系谁.   文件内容: 紧接着版权许可和作者信息之后, 每个文件都要用注释描述文件内容. 通常, .h 文件要对所声明的类的功能和用法作简单说明. .cc 文件通常包含了更多的实现细节或算法技巧讨论, 如果你感觉这些实现细节或算法技巧讨论对于理解 .h 文件有帮助, 可以将该注释挪到 .h, 并在 .cc 中指出文档在 .h. 不要简单的在 .h 和 .cc 间复制注释. 这种偏离了注释的实际意义. 7.3. 类注释 每个类的定义都要附带一份注释, 描述类的功能和用法. // Iterates over the contents of a GargantuanTable.  Sample usage://    GargantuanTable_Iterator* iter = table->NewIterator();//    for (iter->Seek("foo"); !iter->done(); iter->Next()) { //      process(iter->key(), iter->value());//    }//    delete iter;class GargantuanTable_Iterator {    ...}; 如果你觉得已经在文件顶部详细描述了该类, 想直接简单的来上一句 “完整描述见文件顶部” 也不打紧, 但务必确保有这类注释. 如果类有任何同步前提, 文档说明之. 如果