注释虽然写起来很痛苦, 但对保证代码可读性至关重要. 下面的规则描述了如何注释以及在哪儿注释. 当然也要记住: 注释固然很重要, 但最好的代码本身应该是自文档化. 有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字.
你写的注释是给代码读者看的: 下一个需要理解你的代码的人. 慷慨些吧, 下一个人可能就是你!
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 { ...};
如果你觉得已经在文件顶部详细描述了该类, 想直接简单的来上一句 “完整描述见文件顶部” 也不打紧, 但务必确保有这类注释.
如果类有任何同步前提, 文档说明之. 如果
|