5.2.2  注释的风格（1）

每个组织注释代码的方法都不同。在某些环境中，为了让代码文档具有统一标准，需要使用特定的风格。在其他环境中，注释的数量以及风格由程序员决定。下面的示例给出了注释代码的几种方法。

1. 每行都加入注释

避免缺少文档的方法之一是在每行都包含一条注释。每行代码都加入注释可以保证您编写的所有内容都具有特定的理由。但在实际中，如果代码非常多，这么多的注释是混乱、繁琐而无法做到的。例如，考虑下面没有意义的注释：

int result;                                                                 // Declare an integer to hold the result.  
result = doodad.getResult();        // Get the doodad's result.  
if (result % 2 == 0) {                          // If the result mod 2 is 0 ...  
logError();                                                     // then log an error,  
} else {                                                                // otherwise ...  
logSuccess();                                   // log success.  
}                                                                                       // End if/else  
return result;                                          // Return the result  

if (result % 2 == 0) {                          // If the result mod 2 is 0 ... 

if (result % 2 == 0) {                          // If the result is even ... 

修改后的注释给出了代码的附加信息，尽管对于大多数程序员而言这非常明显。结果对2求模是因为代码需要检测结果是否是偶数。

尽管注释太多会有冗长以及多余的倾向，但是当代码很难理解时这样做还是有必要的。下面的代码也是每行都有注释，但是这些注释确实有用。

// Call the calculate method with the default values.  
result = doodad.calculate(getDefaultStart(), getDefaultEnd(), getDefaultOffset());  
// To determine success or failure, we need to bitwise AND the result with  
// the processor-specific mask (see "Doodad API v1.6", page 201).  
result &= getProcessorMask();  
// Set the user field value based on the "Marigold Formula. "  
// (see "Doodad API v1.6", page 136)  
setUserField((result + kMarigoldOffset) / MarigoldConstant) + MarigoldConstant);  

这段代码的环境不明，但是注释可以让您理解每行代码的作用。如果没有注释，很难解释与&以及神秘的"Marigold Formula"相关的计算。

通常没必要给每行代码都添加注释，但是如果代码非常复杂因而需要这样做的时候，不要只是将代码翻译成英语：要解释代码实际上在做什么。

2. 前置注释

您的团队可能决定所有的源文件都使用标准注释。这是记录程序以及特定文件重要信息的好机会。您可能想在每个文件的顶部加入说明信息，下面给出了一些示例信息：

最近的修改日期

原始作者

前面所讲的修改日志

文件给出的功能ID

版权信息

文件或者类的简要说明

未完成的功能

已知的bug

您的开发环境可能允许创建模板，从而自动启动具有前置注释的新文件。某些源代码控制系统(例如并发版本系统，CVS)甚至可以帮助填写元数据。例如，如果您的注释包含了字符串$Id$，CVS将自动扩展注释，包含作者、文件名、版本以及日期。下面的示例给出了一个前置注释：

/*  
* $Id: Watermelon.cpp,v 1.6 2004/03/10 12:52:33 klep Exp $  
*  
* Implements the basic functionality of a watermelon. All units are expressed  
* in terms of seeds per cubic centimeter. Watermelon theory is based on the  
* white paper "Algorithms for Watermelon Processing."  
*  
* The following code is (c) copyright 2011, FruitSoft, Inc. ALL RIGHTS RESERVED  
*/