改善C++ 程序的150个建议学习之建议22：灵活地使用不同风格的注释
2013-09-12 08:43
417 查看
建议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++语言中同时存在，所以我们可以充分地利用两种注释的长处，并注意可能存在的问题，这会让我们的编码变得更加轻松、便利、高效！
注释，可以说是计算机程序中不可或缺的一个部分，它的存在让我们阅读程序代码、理解作者意图变得相对容易（当然，这里说的是具有良好注释的代码）。在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++语言中同时存在，所以我们可以充分地利用两种注释的长处，并注意可能存在的问题，这会让我们的编码变得更加轻松、便利、高效！
内容来自用户分享和网络整理，不保证内容的准确性，如有侵权内容，可联系管理员处理 
相关文章推荐
- 改善C++ 程序的150个建议学习之建议24：尽量采用C++风格的强制转型
- 改善C++ 程序的150个建议学习之建议15：尽量不要使用可变参数
- 改善C++ 程序的150个建议学习之建议19：明白在C++中如何使用C
- 改善C++ 程序的150个建议学习之建议4：小心宏#define使用中的陷阱
- 改善C++ 程序的150个建议学习之建议20：使用memcpy()系列函数时要足够小心
- 改善C++ 程序的150个建议学习之建议35：使用内存池技术提高内存申请效率与性能
- 改善C++ 程序的150个建议学习之建议20：使用memcpy()系列函数时要足够小心
- 改善C++ 程序的150个建议学习之建议12：优先使用前缀操作符
- 改善C++ 程序的150个建议学习之建议28：new/delete与new[]/delete[]必须配对使用
- 改善C++ 程序的150个建议学习之建议14：小心typedef使用中的陷阱
- 改善C++ 程序的150个建议学习之建议23：尽量使用C++标准的iostream
- 改善C++ 程序的150个建议学习之建议7：时刻提防内存溢出
- 改善C++ 程序的150个建议学习之建议18：正确区分void与void*
- 改善C++ 程序的150个建议学习之建议26：用引用代替指针
- 改善C++ 程序的150个建议学习之建议1：区分0的4种面孔
- 改善C++ 程序的150个建议学习之建议8：拒绝晦涩难懂的函数指针
- 改善C++ 程序的150个建议学习之建议7：时刻提防内存溢出
- 改善C++ 程序的150个建议学习之建议10：优化结构体中元素的布局
- 改善C++ 程序的150个建议学习之建议30：new内存失败后的正确处理
- 改善C++ 程序的150个建议学习之建议33：小心翼翼地重载operator new/ operator delete