C++学习笔记----2、使用C++进行优雅编程（三）----注释风格

        每个组织或者说每家公司都有自己的注释风格，没有规矩不成方圆，在编程领域，这条规则依然成立。对于注释，也有各自的要求，在编程规范中都有规定。有时候，这种规定比较松，比如说要写多少注释，以及用什么样的风格都由程序员自己来决定，下面我们就来看一看代码注释的几种方式。

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 modulo 2 is 0 ...
	logError();					// then log an error,
}else {							// otherwise ...
	logSuccess();				// log success.
}								// End if/else.
return result;					// Return the result.

        这样的注释真是让人无语，稍微懂点英文的同学都可以看懂未加注释的代码，只要你有基本的C++知识，也知道这段代码是做什么用的，这种注释完全背离了我们程序中加注释的初心。这只是一个极端的例子，我们还是要基于这个例子来向大家说一些干货的，我们来看其中的一行：

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

        这句注释就是对代码的翻译，着实无用。没有解释为什么用2去除，看修改成如下注释：

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

        哎，好像有点儿意思了，不单纯是代码本身了，代码本身给出的信息被注释得更明晰了，长时间之后，就能理解，原来当初是要干这件事儿。这段儿代码是来检查数字是否是偶数。

        我们再次声明，讲解代码注释的目的依然是初心：让代码本身更清晰地表达自己，在代码清晰表明自我的前提下，代码注释越少越好。那我们改进这段儿代码的思路就出来了，将代码与注释合二为一，将这段儿代码放到一个所见即所得的函数中不就解决问题了。

bool isEven(int value) { return value % 2 == 0; }

不用加注释的代码如下：

if (isEven(result)) {

        每行注释看起来多余臃肿，但在一些难以理解的代码中，注释还是多多益善的，下面的代码来自真实案例，也是每行都注释，但却确实有用：

// Calculate the doodad. The start, end, and offset values come from the
// table on page 96 of the "Doodad API v1.6."
result = doodad.calculate(Start, End, Offset);
// 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 + MarigoldOffset) / MarigoldConstant + MarigoldConstant);

        该注释解释了每一行要做什么，如果没有这些注释，对于"Marigold Formula"的计算大家肯定是一头雾水，无法解密吧。

        再多说一句，不做无谓的代码注释，注释的内容都是代码本身无法表达的，更不要去翻译代码的每一行，真的没有什么用。

1.2、前缀注释

        你的公司可能会要求在源码的前面加上一段儿标准注释，说明代码的重要信息，可能会包含如下信息：

• 版权信息
• 文件/类的简述
• 未完成的特性*
• 已知缺陷*

*号注释的内容是与缺陷与特性跟踪系统相关的。

        还有一些信息是不要包含在注释中的，这些信息在版本控制系统中都有。

• 最后修改日期
• 原作者
• 修改日志
• 特性ID

举例如下：

// 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 2023, FruitSoft, Inc. ALL RIGHTS RESERVED

1.3、固定格式注释

        固定格式的注释是为相关工具服务的，按照固定格式对代码进行注释，利用相关工具就可以直接生成与代码相关的文档，而不用人员再进行手工整理，让一切标准化，学习过Java的同学都很清楚，JavaDoc就可以做到生成Java的相关文档。在C++中，也有相关工具，本次推荐Doxygen的免费工具，大家可以到doxygen.org上去下载，使用起来也比较容易，我关于这部分，我就不过多介绍了。

1.4、特别注释

        大部分时间，注释是基于需要而产生的，下面给出几点需要考虑的

• 在加注释之前，看一下能否通过修改代码而不要注释--例如，重命名变量、函数、类等；重新将步骤排序；用一些中间命名的变量等等。
• 想像一下，如果别人要读你的代码，如果哪一部分容易出现疑惑，就将其进行注释。
• 不要将版本控制系统中默认包含的信息写到注释中。
• 使用API时要将其引用信息进行注释
• 更新代码时要相应对注释进行更新，不一致的代码与注释更令人迷惑。
• 在将函数分段注释时，要考虑是否可以将函数分解成子函数
• 不要在注释中加入冒犯性及侮辱性的词语，这种雷还是不要自己埋，说不定哪天谁看到了你的代码，雷就爆了。
• 内部可接受的笑话是否可以加入注释中，要与你的经理进行确认。

1.5、自动生成文档的代码

        我们一再强调，好的代码是不需要多余的注释的。最好的代码是易于阅读的，如果像前面介绍的那样，对每一行代码都加了注释，就需要考虑对代码进行重写了。例如，使用描述性的名字来对函数、参数、变量、类等进行命名。合理使用const常量；如果变量不会被修改，就要加上const。对函数中的步骤重新排序，使其更易阅读。使用中间变量使算法更易理解。记住C++是一种编程语言，主要目的是让计算机好好工作，其语法也是被用于向读者解释其意思的。

        另外一种方式就是对代码进行分解，我们下一篇文章再谈。