5.2.1 使用注释的原因（3）
3. 传递元信息的注释
使用注释的另一个原因是在高于代码的层次提供信息。元信息提供创建代码的详细信息，但是不涉及代码的特定行为。例如，您所在的组织可能想要使用元信息跟踪每个方法的原始作者。您还可以使用元信息引用外部文档者其他代码。
下面的示例给出了元信息的几个实例，包括文件的作者，创建日期，提供的特性。此外还包括了表示元数据的行内注释，例如对应于某行代码的bug编号，还有注释提醒以后重新访问代码中可能存在的某个问题。
- /*
- * Author: marcg
- * Date: 110412
- * Feature: PRD version 3, Feature 5.10
- */
- int saveRecord(Record& rec)
- {
- if (!bDatabaseOpen) {
- throw DatabaseNotOpenedException();
- }
- int id = getDB()->saveRecord(rec);
- if (id == -1) return -1; // Added to address bug #142 – jsmith 110428
- rec.setId(id);
- // TODO: What if setId() throws an exception – akshayr 110501
- return id
- }
在每个文件的开头还可以包含修改日志。下面给出了一个修改日志的示例。- /*
- * Date | Change
- *----------+--------------------------------------------------
- * 110413 | REQ #005: <marcg> Do not normalize to maximum
- * | value if values > 32767.
- * 110417 | REQ #006: <marcg> use nullptr instead of NULL.
- */
然而，如果您使用第23章讲述的源代码控制方案，就不需要这么做。所有的源代码控制方案(例如CVS)都支持签入注释(check-in comments)，您应该分别签入每个修改请求。例如，如果您需要在一个文件中处理两个修改请求，应该签出(check-out)文件，处理第一个修改请求，然后签入文件并给出适当的修改日志注释。之后才再次能签出文件并处理第二个修改请求。如果您想要同时处理两个修改请求，可以将源文件分成两个分支，然后在一个分支中处理第一个修改请求，在第二个分支中处理第二个修改请求。当执行结束时，可以将两个分支合并，每个分支都有恰当的修改日志注释。通过这种方法，您不需要在每个文件的开头手动维持修改日志。
注释很容易走向极端。最好与您的团队讨论那种类型的注释最有用并制定一个方针。例如，如果团队的某个成员使用"TODO"注释表明代码仍然需要加工，但是其他人不知道这个约定，这段危险的代码可能就会被忽略。
如果团队决定使用元信息注释，那么所有人都要包含相同的信息，否则文件会不一致。