C++编程规范 头文件格式 和 函数注释格式

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留着以后实现那功能也行,注释信息一般可以写上你的名字和邮箱,然后说下待实现的功能或其他事项

C++编码规范(2):命名规范

如果你代码中的变量名,函数数,类名都取得很好,不仅是个有意义的词或短语,而且确切的表达了该变量或函数的功能.那读起代码来就像看文章一样,绝对是一种享受.当然理想是美好的,现实可是残酷的.很少有人能做到这样.一来嘛你英语词汇量得多,不样不容易找到那么多合适并贴切的词.二来就是有些词组合就会很长,这样不得不用些缩写,而缩写就不是每个人都认识,对一些人来说和无意义的字母没啥区别,只要你英语好才能一眼瞧出来.

    当然当你使用一个编程语言的话,里面已经弄出很多词来做关键字了,当你看熟了看多了后就会看着很舒服很顺眼.但如果你学个啥框架,比如MFC,突然发现那么多宏名,还有一些类型名(其实也是宏转换整出来的). 就会觉得非常不顺眼,非常丑陋.这些类型名大部分是一些缩写,虽然是代表着确切的意思,但由于缩写的太厉害了,你跟瞧着一堆没意义的字母没啥区别.当然你要用多了看着也就顺眼了.

关于命名有两个比较出名的专业名词:Hungarian(匈牙利) , Camel(骆驼) , Pascal(帕斯卡)

匈牙利命名法

变量名=属性+类型+对象描述.

例如int m_iNumber;

如果是局部变量一般就不需要属性了,所以就是int iNumber;

1.其中对象描述的名称都要求有明确含义，可以取对象名字全称或名字的一部分.可以起自解释的作用,从名字中就可以看出变量的功能.

2.其中属性(有个下划线)包括: g_表示全局变量,  c_表示常量 , m_表示C++类成员变量, s_ 表示静态变量 , sm_表示静态成员变量

3.类型部分都是用类型关键字的缩写表示:

据说这种命名法是一们叫Charles Simonyi的匈牙利程序员发明的,他也在微软工作过.所以你查看MFC中的一些源码会发现都用的匈牙利命名法,你要是开发中用到MFC可能也倾向于使用这种命名规范.

优点与缺点:

匈牙利命名的优点显而易见,能从名字本身获取到很多信息,知道变量的类型或要实现的功能.

缺点是添加这些前缀会使变量名变长,变量名一长就会显得不雅,另外就是开发人员要多敲几个字母.当然还有其他很多缺点.

另外就是匈牙利命名主要针对基本类型变量名,但在面向对象语言中肯定到处是类名和函数名,那类名和函数名该怎么取呢? 此时在它们前面加个啥前缀没有太多意义的.

此时变量名=属性+类型+对象描述 ,中最有对象描述这一项可派得上用场了,但是对象描述可没给我们带来啥明确的格式指导,比如描述信息一长,就很不利于我们眼睛的识别.

于是就需要一些规范应用于对象描述的格式,另外一些命名规范就出现了.

驼峰命名法

骆驼有一个很明显的特征就是背像个山峰一样,有凹下去与凸起来的部分.

于是这种命名法就借鉴了这个特征,让变量名通过某些字母大写来达到凹凸的效果,这有利于眼睛识别,因为如果都是小写或大写都不利于眼睛识别.

小驼峰命名法

除第一个单词首字母小写,其他单词首字母大写.

例如 int myPhoneNumber;

大驼峰命名法(又叫Pascal法)

所以单词首字母大写

例如 void GetPhoneNumber();

实际上驼峰命名法与匈牙利命名法并不冲突,有时还可以综合使用.

匈牙利法是

变量名=属性+类型+对象描述

我们可以让前两者不变,只在对象描述中应用驼峰法.当然了也可以中单独使用驼峰法,不需要属性和类型信息.

在C#中基本上习惯上只使用驼峰法,不再需要属性或类型的信息.因为VS这开发环境的智能感觉支持的非常好,你把鼠标放哪个变量上会马上显示出类型等相关信息.而且由于C#中在隐式类型转换时要求较严,必须是精度不会降低,不会出现溢出.所以类型信息对我们用处也不是太大了.最重要的是对象描述的功能性信息了.

一般函数名和类名都用大驼峰命名法,不过在MFC中类名一般推荐是匈牙利与驼峰结合的变体,类前面加一个大写的字母C,后面部分就是大驼峰法了

下划线命名法

就是单词之间用下划线连接

比如int MY_NUMBER;

一般用的不多,不过像PL/SQL里面就用的特别多,因为PL/SQL不像C++和C#变量是区分大小写的.所以下划线可能更好点.

在C++中一般宏都全部大写,然后单词间用下划线分开.

C++ 头文件格式和函数注释格式

-----------------------------------------------稍作修改-------------------------------------------------------