C++编码规范(1):代码注释

当你阅读别人的代码时如果没有注释那会是件比较痛苦的事.一说到注释我们马上想到是通过//或/* */这样来添加一些描述信息.这只是狭义的注释.

广义的注释我们可以理解为,任何有助于理解代码的信息都可以看成注释.

我们可以把写代码和写文章类比下.自然语言会有词法,句法,语义这几个概念.代码中的语法和句法就相当于一个编程语言中的基本语法规范.这是我们学习一门编程语言必须掌握的.所以注释的时候一般不会涉及到这些信息.

注释主要涉及到语义的描述.语义从大的方向,软件产品面向的应用来说,就是要解决的问题本身的逻辑,如果是些应用软件也可以叫业务逻辑.我们把业务逻辑理清头绪后就会来个啥数据建模之类的.然后写设计文档之类的,有啥概要设计与详细设计,这些文档可以看成非常重要的注释.

然后就是写到代码里的注释了,通过//或/* */标识出来.还有一种注释叫自我注释,就是通过函数或变量名字就得得到一些有用的信息

 

这里主要讲下用//或/* */做的注释

用// 还是/* */就看你自己的偏好了.最重要的是保持一致,就是在一个项目中大家达成一致,全部用哪一种或者在某个地方用//,另外的地方用/* */

 

注释的位置及常见内容

 

1.文件注释

在C++的代码都是分布在一个个的头文件和源文件中,如果是用的VS则是h后缀文件和cpp后缀文件. 当然了有时你用以内联函数还可能会有inl文件.每个文件的开头部分你可以添加注释信息.

内容一般是:版权,作者,编写日期,功能描述.例如

/**************************************************************************

Copyright:MyCompany

Author: Arwen

Date:2013-01-09

Description:Provide  functions  to connect Oracle

**************************************************************************/

或者

//Copyright:MyCompany

//Author: Arwen

//Date:2013-01-09

//Description:Provide functions to connect Oracle

 

有时如果修改了代码,还可以添加修改人,日期,修改内容有目的这些信息.

 

2.类注释

一般是简单的说下这个类的功能,如果你在文件开头已经描述了这里也可以省略.如果要注释的话就可以这样简单的描述下.

// COleDataObject -- simple wrapper for IDataObject

class COleDataObject
{

}

或者

/*COleDataObject -- simple wrapper for IDataObject*/

 

3.函数注释

描述函数的功能及参数,其他相关信息.例如

//Summary:  connect the database

//Parameters:

//       connInfo:A class contains the connect info ,such as user name ,pwd,etc.

//       directConnect : use TNS name or use direct connection info

//Return : true is connect successfully.

bool ConnectDatabase(ConnectInfo connInfo, bool directConnect);

 

或者

/*

*Summary: connect the database

*Parameters:

*     connInfo:A class contains the connect info ,such as user name ,pwd,etc.*    

*     directConnect : use TNS name or use direct connection info

*Return : true is connect successfully.

*/

 

 

4.变量注释

一个变量如果代表的意思不容易从变量名看出来,而且又挺重要的话最好也加点注释.例如

UINT m_nGrowBy;     // number of cache elements to grow by for new allocs

或者

UINT m_nGrowBy;     /* number of cache elements to grow by for new allocs*/

 

5.实现注释

在一些逻辑性很强,不容易理解的代码块前添加注释.特别是是像一些算法,看起来就几行,但想个半天都未必明白到底是啥意思来着.

例如

// copy elements into the empty space
 while (nCount--)
      m_pData[nIndex++] = newElement;

还有就是如果想针对函数的某些个参数做些注释,那最好把参数分几行写.

void MyFunction(string name, //This is my name

                         int age)

 

另外有时一个函数很长,里面有奶多个大括号{ } ,这样一嵌套,有时你不知道谁对应谁了,你要往里面插入代码就容易出错.你也可以在些结尾的大括号加个注释,表明它是哪个if或while语句的结束处.

在C#中是可以通过#region 加 #endregion 来做注释.同时开发环境VS能提供支持让你方便的折叠这样注释的代码.

VS也支持在C++中通过#pragma region 与 #pragma endregion来做注释,但这在其它编译器中不会被识别,所以需要考虑到跨平台的话或者会使用不同的编译器的话就最好别用.

 

6.TODO 注释

todo的意思就是待做的事.比如你代码写了一半,然后下班了.为了方便你第二天很快的找到那具体地方,或者防止你忘记.就可以用todo注释下.因为一些开发环境提供了对它的支持,可以让你方便的找到哪些个地方有todo注释,起个书签的作用.你选View-->Task List,然后在下面的下拉列表中选择comments就会列出所有TODO注释信息.

另外你也可以写个TODO留着以后实现那功能也行,注释信息一般可以写上你的名字和邮箱,然后说下待实现的功能或其他事项

Reference:

1:http://blog.csdn.net/weiwenhp/article/details/8484973#t3