改善C++ 程序的150个建议学习之建议22：灵活地使用不同风格的注释

建议22：灵活地使用不同风格的注释
注释，可以说是计算机程序中不可或缺的一个部分，它的存在让我们阅读程序代码、理解作者意图变得相对容易（当然，这里说的是具有良好注释的代码）。在C/C++语言中，存在着两种不同的注释语法：
旧有的C风格的注释：     /* describe your purposes */
新式的C++风格的注释： // describe your purposes
既然两种注释语法都有效，选择哪一种呢？C风格的还是C++风格的呢？很多的C++书籍推荐我们使用新式的C++风格注释语法，比如受C++程序员顶礼膜拜
的经典书籍《Effective C++》在条款4中的建议就是如此。为此，Scott Meyers还给出了一定的理由—由“内嵌注释结束符”引发的“惨案”：
/* C风格的注释*/
if(a>b)
{
/* int temp =a;  /* swap a and b */
a = b;
b = temp;
*/
}
此段代码取自Scott Meyers的《Effective C++》，在此表示感谢。
// C++风格的注释
if(a>b)
{
//int temp =a; // swap a and b
//a = b;
//b = temp;
}
当程序员因为某些特殊原因而采用C风格的注释语法将上述代码进行注释时，由于原代码中存在原有的内嵌注释，导致注释过早地找到结束匹配符，使代码注释失效，出现编译错误。而C++风格的注释则不会出现类似的麻烦。然而，正如一个硬币有两面，任何东西都是有利有弊的。让程序员更加便利与轻松才是硬道理。使用注释亦然。还是先看下面的一段代码：
/***
* new.cxx - defines C++ new routine
*
* Copyright (c) Microsoft Corporation. All rights reserved.
*
*Purpose:
* Defines C++ new routine.
*******************************************************/
#ifdef _SYSCRT
#include <cruntime.h>
#include <crtdbg.h>
#include <malloc.h>
#include <new.h>
#include <stdlib.h>
#include <winheap.h>
#include <rtcsup.h>
#include <internal.h>
void * operator new( size_t cb )
{
void *res;
for (;;) {
// allocate memory block
res = _heap_alloc(cb);
// if successful allocation, return pointer to memory
if (res)
break;
// call installed new handler
if (!_callnewh(cb))
break;
// new handler was successful -- try to allocate again
}
RTCCALLBACK(_RTC_Allocate_hook, (res, cb, 0));
return res;
}
#else /* _SYSCRT */
这是VC++库中new.cpp文件中的部分代码。在注释方面，这段代码中有很多值得我们学习的地方。使用C风格的 /*  */标准化的代码有很多必不可少的东西，比如版权信息、文件名称、标识符、摘要、当前版本号、作者/修改者、完成日期、版本历史信息，等等。这些信息不会为我们的代码运行带来任何的改进，但是可以提高了代码的可读性，方便代码的维护。如此繁缛的信息，可能多达十几行，此时如果使用C++风格的注释语法，那么就得记得在每一行的开始都写下两个“/”符。那此时何不采用更加简单便利的/*  */呢？内嵌注释用 //内嵌注释一般出现在代码主体内。此时，建议使用新式的C++风格的注释语法。最直接的原因就是避免出现那些由“内嵌注释结束符”引发的“惨案”。不过，在这种情况下，出于调试原因用/* */注掉一块代码，也不会出现什么问题。宏尾端的注释用/* */   Scott Meyers对于注释语法的使用还提出了一个问题：一些“古董”级的、只针对C编译器而写的预处理器不能识别C++风格的注释，所以下面的代码就不能按照预期那样正常运
行，它们会把注释当成宏的一部分：
#define LIGHT_SPEED 3e8 // m/sec (in a vacuum)
虽然使用这样的“古董”预处理器的人近乎绝迹，但是保不齐会出现一个特例。所以为了保证百分之百不出错，建议在宏尾端的注释使用C风格的注释语法：
#define LIGHT_SPEED 3e8 /* m/sec (in a vacuum) */
除此之外，还有一个特别的使用情形：默认参数函数的定义。代码片段如下所示：
// 声明文件
class A
{
public:
void Function( int para1, int para2 = 0 );
};
// 实现文件
void A::Function( int para1, int para2 /* = 0*/ )
{
// processing code
}
我们一般将类的声明与实现进行分离，放置在不同的文件之中。此时如果函数存在默认参数，它只能出现在声明中，不过，在实现中缺少默认参数的说明可能会影响我们对函数的设计或理解，所以有必要在实现中对默认参数进行一些说明。使用C风格的注释语法按照上述形式进行说明确实是一个值得推荐的方式。在这种情形下，C++风格的注释变得无能为力了。灵活地使用两种形式的注释方式，在保证代码鲁棒性、可读性的同时，尽量使程序员获得更多轻松与便利。
请记住：C风格的注释/* */ 与C++风格的注释// 在C++语言中同时存在，所以我们可以充分地利用两种注释的长处，并注意可能存在的问题，这会让我们的编码变得更加轻松、便利、高效！