C\C++代码编写规范 Version 1.2 C\C++代码编写规范 Ver1.1 １ § 1 目的 使用统一编码编写规范的主要原因，是使应用程序的结构和编码风 格标准化，使其他成员共享劳动成果。 本规范 注重于程序的物理结构 和外观，而不是程序的逻辑结构。它们使其他人的编码更加容易阅 读、容易理解而且容易维护。 § 2 命名规则 总则：命名要用英语，单词简单，明了，意义明确。每个单词的 第一个字母应该大写，单词与单词之间直接连接，用大写字母加 以区别，定语应该放在被修饰语的前面.不能放在被修饰语的后 面.。函数名称和工程名称杜绝直接使用 A,B,C,1,2,3,汉语拼音或人 名等难以理解的单词，对于变量名称也要避免 如此命名。命名书 写的基本原则是匈牙利命名法.复杂变量 (复杂变量变量指,类和结 构的实例)应该有统一的缩写原则和常用变量的缩写列表. 命名的长度应当符合“min-length && max-information”原则。一般 来说，长名字能更好地表达含义。单字符的名字也是有用的，常见的 如 i,j,k,m,n,x,y,z 等，它们通常可用作函数内的局部变量 § 2.1 工程命名 工程项目的意义名称根据项目组讨论决定.并在此工程意义名称的前面 添加大写的“SS”(ShangHai Smisol )作为此工程项目的工程命名。 如：工程项目的意义名称为 Model，工程名称为 SSModel 对应的 Visual C++的工程文件名为 SSModel.dsp 工程名暂时不作要求：PC 版使用 AutoNavi ；CE 版本使用 Plugin; C\C++代码编写规范 Ver1.1 ２ § 2.2 类(CLASS)的命名 所有的类（ＣＬＡＳＳ）的名字必须以“CSS“开头．“CSS “后第 一个字母应该大写．Ｅｘａｍｐｌｅ： CSSImage．所以对于类（Ｃ ＬＡＳＳ）的头文件和原文件，遵循ＶＣ的命名规则．去掉字母Ｃ即 可.Example : SSImage.h，SSImage.cpp 类名称延续传统的命名方法，是对话框的名称后面加 Dialog（由工具 生成），不是的就不用了，一般现在的情况不需要加其他的类。需要 的话，以功能描叙为主 § 2.3 函数的命名 § 2.3.1 全局函数 全局函数的命名必须符合 ：限定名词 + 动词 [+名词] 的原则。 如：long RmodelGetCenter(double &x, double &y) 的 Rmodel 为限定名 词 Get 为动词 Center 为名词。限定名词根据工程名称统一规定。 函数命名主要是功能简短描写，可以使缩写，不能缩写成一两个 字母的描述，最好是简单易懂的英文。 § 2.3.2 类成员函数 类成员函数的命名必须符合：动词[+名词]的原则。如：在 CRImage class 中 void GetWidth(double *Width) 名词 Get 为动词 Width 为名词。类的成员函数只使用“动词”，被省略掉的名词就是对象本 身。例如： RmodelDrawImage(); // 全局函数 Image->Draw(); // 类的成员函数 成员函数和全局函数命名规则一样，暂时不作区别 § 2.4 宏 全部要用大写字母。并用下划线分割单词。如： #define MAX_IMAGE_LENGTH 1024 宏定义就如上所述 C\C++代码编写规范 Ver1.1 ３ § 2.5 文件的命名 § 2.5.1 头文件(H)，代码文件(CPP) l 对于类（CLASS）的头文件和代码文件的命名遵循ＶＣ的命名 规则.去掉字母Ｃ即可。Example ：对于 CSSImage class 头文件 和代码文件分别为 SSImage.h,SSImage.cpp. l 对于全局函数的头文件和代码文件的命名，应该遵循: SS+ 限定 名词+[其他] + cpp/H。如 SSRmodelCreate.h 和 SSRmodelCreate.cpp.其中 SS 为文件名前缀，Rmodel 为限定词， Create 表明此代码文件是产生关于 Rmodel 的文件。 类文件名就不作修改了，对话框类使用工具产生的文件名 § 2.5.2 资源文件 资源文件与工程文件同名，仅仅后缀不同而已。如：对于 SSModel.dsp 而言，资源文件名称为 SSModel.rc. 资源文件命名以内容为主 § 2.5.3 def 文件 def 文件因该与工程文件同名，仅仅后缀不同而已。如：对于 SSModel.dsp 而言，def 文件名称为 SSModel.def. def 文件命名以内容为主 以下规则都不修改 § 2.6 变量的命名 变量的命名应该遵循匈牙利命名法。即：[限定词 + ‘_’ + ] 类型缩写+ 意义名词。 § 2.6.1 全局变量的命名 全局变量的限定词为字母”g”。所以全局变量必须以小写字母”g_”开 始。如 int g_nImageNumber ：“g“表示全局变量“n“表示此变量为 int 型 , “ImageNumber“表示此变量的意义。 § 2.6.2 局部变量的命名 局部变量不必要加限定词。即：类型缩写+意义名词。如 int nImageNumber ： “n“表示此变量为 int 型 , “ImageNumber“表示此 变量的意义。 C\C++代码编写规范 Ver1.1 ４ § 2.6.3 类中的成员变量的命名 类中的成员变量命名的限定词为字母”m”。所以类中的成员变量命名 必须以小写字母” m_”开始。如 int m_nImageNumber ：“m“表示 类中变量 “n“表示此变量为 int 型 , “ImageNumber“表示此变量的意 义。 § 2.6.4 静态变量 静态变量加限定词为”s”，所以对于类中的成员静态变量命名必须以 小写字母” ms_”开始。如 int ms_nImageNumber ：“ms“表示类中 成员静态变量 “n“表示此变量为 int 型 , “ImageNumber“表示此变量 的意义。 对于局部的静态变量命名必须以小写字母” s_”开始。如 int s_nImageNumber ：“s“表示静态变量 “n“表示此变量为 int 型 , “ImageNumber“表示此变量的意义。 § 2.6.5 指针 在所有的指针的类型缩写前必须加前缀”p”。如对于类中的成员指针 变量必须以小写字母” m_p”开始。如 int *m_pnImageNumber ：“m “表示类中成员变量 “pn“表示此变量为 int * 型 , “ImageNumber “表示此变量的意义。 § 2.6.6 常量的命名 常量必须全部用大写字母，不需要加前缀，当常量由多个单词组成 时，各单词由“_”加以分割。并且用 const 来定义常量（称为 const 常量）。如： const int MAX_NUMBER = 100;// C++ 语言的 const 常量 const float PI = 3.14159; // C++ 语言的 const 常量 需要对外公开的常量放在头文件中，不需要对外公开的常量放在定义 文件的头部。为便于管理，可以把不同工程的常量集中存放在一个公 共的头文件中。 § 2.6.7 参数的命名 参数的命名和局部变量的命名相同。。即：类型缩写+意义名词。如 long GetImageNumber(int &nImageNumber) ： “n“表示此变量为 int 型 , “imageNumber“表示此变量的意义。 C\C++代码编写规范 Ver1.1 ５ § 2.7 其他 § 2.7.1 类型(TYPEDRFED) 命名 类型(typedef )的命名不作具体要求。但第一个字母应该用大写字母。 如： typedef PWORD IMGPTR ; // 16 bit image buffer pointer 或 typedef PWORD Imgptr; // 16 bit image buffer pointer § 2.7.2 枚举(enum) 枚举类型的的命名中， 单词与单词之间直接连接，用大写字母加以区 别，并且加大写的字母”EM”作为前缀。枚举列表值的命名必须遵循 常量的命名规则。全部用大写字母,当由多个单词组成时，各单词 由”_”加以分割 如： enum EMClockDirecter{CLOCKWISE=1,ANTICLOCKWISE=-1}; § 2.7.3 联合(union) 联合类型的的命名中， 单词与单词之间直接连接，用大写字母加以区 别，并且加大写的字母”UN”作为前缀。联合包含的类型数据的命名 必须遵循局部变量的命名规则。如： union UNKnow // Declare union type { char chType; // Declare member types int nNumber; float fValue; } § 2.7.4 结构(struct) 结构类型的的命名中， 单词与单词之间直接连接，用大写字母加以区 别，并且加大写的字母”ST”作为前缀。结构包含的类型数据的命名 必须遵循局部变量的命名规则。如： struct STPerson // Declare PERSON struct type { int nAge; // Declare member types float fWeight; }; C\C++代码编写规范 Ver1.1 ６ § 3 注释规则 使用代码注释的目的: l 用文字说明代码的作用(即为什么要编写该代码,而不是如何编写); l 明确指出该代码的编写思路和逻辑方法; l 使人们注意到代码中的重要转折点; l 使代码的阅读者不必在他们的头脑中仿真运行代码的执行过程。 空行和空白字符也是一种特殊注释 注释可以与语句在同一行，也可以在上行，禁止在下面注释。 规定在所有的注释中都以‘//’开始，‘/*‘和‘*/’之间的代码仅表 示此段代码暂时且不用。在注释中所有的标示符都必须用窄字符。 注解的两种方式： l 简单的说明，必须与代码同一行或上行，用“//“开始。如 if(value>0)//if value greater than 0. execute … l 详细的说明，必须在代码上方，用“//@Description： “标 示开始进行说明，用“//@~Description “标示结束。如： //@Description： //if value greater than 0. execute … //@~Description if(value>0) { …… } § 3.1 工程的注释 工程的注解说明应该书写入工程的说明文档。应该包括： ● 项目的委托单位、开发部门； ● 该软件系统与其他系统的关系。 ●定义列出用到的专门术语的定义和缩写词 § 3.2 代码文件注释 代码文件主要是指 h 文件和 cpp 文件。每个代码文件赋予一个注释标 头。代码文件注释标头内容包括:公司名称、版权、作者名称、时间。 C\C++代码编写规范 Ver1.1 ７ 注意一个 CPP 必须有一个人来完成。 请按照下例写注释标头: //************************************************** //@File Name: RAngle.h: the interface of CRAngle //@version : V1.0 //@Copyright: (c) 1998-1999 *********公司技???部 //@Designer : *** //@Creater: : *** //@Begin Date: 2001.10.9 //@End Date : 2001.11.9 //***************** First Modify******************* //@Modfier: //修改人: //@Modfy Date: //@Modfy Context: //************************************************* § 3.3 类的注释 类的说明注释应该放在头文件中 (H 文件中.CPP 文件中无) 类注释的模板为： //@Description： //This class implement the base funciton of image. //CSSImage is the base class of Smiosl Image Group about //image process. Every class when use image please use the //class. do not create new Image //base class . but you can inherit one new class from //CSSImage.This class have CSSmemory member . so the class //can auto manage memory //@~Description //@Example: //CSImage imgName; //ImgName.SetImage(nwidth,nHeight,impBuffer,true); //IMGPTR imBuffer = ImgName.GetAddress(); //@~Example class CSSImage { public: friend class CSSImage; CSSImage();// Construct one empty image C\C++代码编写规范 Ver1.1 ８ //@Description: //Construct one image as same as cIimage,but don't allocate //new image buffer. that means the image buffer is as same //as the buffer of cImage //@~Description CSSImage(const CSSImage &cImage); virtual ~CSSImage(); public: //@Description : //Get the bits depth of the gray image. // the default value is 8; //@~Description size_t GetBits() const; void SetBits(size_t uBits); size_t GetHeight()const; // the height of image } § 3.4 函数注释 函数的简单说明应该放在头文件中，详细的说明请放在 CPP 文件中。 在 H 文件中的注释的模板为: //@Description : //Get the bits depth of the gray image. the default value //is 8; //@~Description size_t GetBits() const; 或 //Get the bits defpth size_t GetBits() const; 在 CPP 文件中函数的注释的模板为: //******************************************************* //@Function Name: //@Parameter [in] int a--- //@Parameter [out] int b--- //@Parameter [in,out] int c--- //@Description: //@Return Value: // 为 1, 表示... // 为 0, 表示... //@Example: Demo about the function //************************************************************* C\C++代码编写规范 Ver1.1 ９ § 3.5 流程注释 按需要进行注释。特别是在主要的判断和循环处加注释，简单的流程 注释要在“{“和“}“的同一行进行说明。复杂的的流程注释要在判 断和循环的上方增加注释。如： void CSImage::SetImage(const CSImage &imgSrc, bool bCopy) { //assert this image != imgSrc assert(this!=& imgSrc); // assert the data mermber of class is valid #ifdef _DEBUG imgSrc.Assert(); #endif ouWidth = imgSrc.ouWidth; ouHeight = imgSrc.ouHeight; ouBits = imgSrc.ouBits; ouLineSize = imgSrc.ouLineSize; if(bCopy) {//allocate memory if bCopy ==true /*@Description : allocate the require size memory and free the before memory */ MemAllocator(ouLineSize*ouHeight); CopyImage(imgSrc);} else{// only pointer imgSrc if bCopy == false oImp = imgSrc.oImp; } // assert the creation image data mermber of class is valid #ifdef _DEBUG Assert(); #endif } § 3.6 变量 变量的注释根据需要在同一行加以说明。如： int nImageNumber //explain the number of image § 3.7 常量 简单注释同变量的注释。如果需要同时要有 16 进制和 10 进制的值 const int COLORNUMBER =255//0xFF. 或 C\C++代码编写规范 Ver1.1 １０ const int COLORNUMBER =255//0xFF. § 4 代码的格式化 基本要求: l 程序结构清析，简单易懂，单个函数的程序行数推荐在 60 行以 内。 l 不要随意定义全局变量，尽量使用局部变量。 l 循环、分支层次不要超过五层。 l 用 IF 语句来强调只执行两组语句中的一组。禁 止 ELSE GOTO 和 ELSE RETURN。 l 用 CASE 实现多路分支。 l 函数只有一个出口。 § 4.1 CLASS 的书写顺序 Public: 1. Type Define 类型定义 Public: 2. Constructor Function 3. Destroy Function Public: 4. Property or Data Member Public: 5. SetParalmeter Method 6. Execute Method 7. GetPalameter Mehod Protected: 8. Type Define 类型定义 Protected: 9. Data Member Protected: 10. Method Privated: 11. Type Define 类型定义 Privated: 12. Data Member C\C++代码编写规范 Ver1.1 １１ Privated: 13. Method 如： class CSImage { public: friend class CSImage; typedef PWORD IMGPTR ; // 16 bit image buffer pointer CSImage(); virtual ~CSImage(); public: __declspec(property(get=GetWidth)) size_t Width; public: void SetWidth(size_t uWidth); long Execute(); size_t GetWidth() const; protected: typedef struct tagPROCESS{ IMGPTR ImpDest; size_t uDestLineSize; size_t uWidth; size_t uHeight; }PROCESS; protected: size_t ouWidth;//image width size_t ouHeight;//image height protected: virtual long Run(const PROCESS &cProcess); private: void SetDefault(); }; § 4.2 变量的初始化 所有变量必需初始化.尤其是指针必须初始化为 NULL. pstSrc = NULL//良好的风格 pstSrc = 0//不良的风格 尽可能在定义变量的同时初始化该变量（就近原则）如果变量的引用 处和其定义处相隔比较远，变量的初始化很容易被忘记。如果引用了 未被初始化的变量，可能会导致程序错误。如 int iwidth = 10; // 定义并初绐化 width int iheight = 10; // 定义并初绐化 height C\C++代码编写规范 Ver1.1 １２ int idepth = 10; // 定义并初绐化 depth § 4.3 对齐方式 所有的对齐都用 TAB 进行对齐(TAB =4 个空格)如： while(……) { if(……) { for(……) { switch(……) { case 1: …… } // switch(……) } // for(……) } // if(……) } // while(……) § 4.3.1 条件编译宏 所有的条件编译宏都必须靠最左边。如： void CSImage::SetImage(const CSImage &imgSrc, bool bCopy) { //assert this image != imgSrc assert(this!=& imgSrc); // assert the data mermber of class is valid if(bCopy) { #ifdef _DEBUG imgSrc.Assert(); #endif } …… } § 4.3.2 括号“}”，“{“对齐方式 程序的分界符‘{’和‘}’应独占一行并且位于同一列，同时与引用它们的 语句左对齐。{ }之内的代码块在‘{’右边一个 TAB 处左对齐。如： for(;;) {// …… }// 良好的风格 for(;;){// C\C++代码编写规范 Ver1.1 １３ ……// }// 不良的风格 § 4.3.3 循环对齐方式 循环体必须另起一行, for、while、do 等语句自占一行，执行语句不 得紧跟其后。建议不论执行语句有多少都要加{}。 for(;;) {//ok dosomething();//良好的风格 }//ok for(;;) dosomething();//不良的风格 § 4.3.4 if 对齐方式 if 语句占一行，执行语句不得紧跟其后。不论执行语句有多少都要加 {}.并且 if 要和其后的程序体的”{“，“}“和“else“在同一列。如： if(…) { …… } else { if(……) { …… } else { …… } } § 4.4 关于 GoTo 的使用 尽量避免 GoTo 的使用，虽然使用 GoTo 可以带来程序结构等许多 方面的好处。但它也带来许多灾难性的后果。而且这些错误都是 很难查出来的。在必须使用 GoTo 的情况下，尽量使用 do { …..} while(false)代替。如：： do { FILE *fp = fopen("f:\\temp\\try1.rfi", "wb"); if (fp == NULL) break; dosomething(); if(……) break; C\C++代码编写规范 Ver1.1 １４ } while (false); § 4.5 空行 空行起着分隔程序段落的作用。空行得体将使程序的布局更加清晰。 在每个类声明之后、每个函数定义结束之后都要加空行 如： // 空行 void Function1(…) { … } // 空行 void Function2(…) { … } // 空行 void Function3(…) { … } 在一个函数体内，逻揖上密切相关的语句之间不加空行，其它地方应 加空行分隔。如： // 空行 while (condition) { statement1; // 空行 C\C++代码编写规范 Ver1.1 １５ if (condition) { statement2; } else { statement3; } // 空行 statement4; } § 4.6 空格 l 关键字之后要留空格。象 const、virtual、inline、case 等关键字 之后至少要留一个空格，否则无法辨析关键字。象 if、for、 while 等关键字之后应留一个空格再跟左括号‘（’，以突出关键 字。 l 函数名之后不要留空格，紧跟左括号‘（’，以与关键字区别。 l ‘（’向后紧跟，‘）’、‘，’、‘;’向前紧跟，紧跟处不留空格。 l ‘，’之后要留空格，如 Function(x, y, z)。如果‘;’不是一行的结 束符号，其后要留空格，如 for (initialization; condition; update)。 l 赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操 作符，如“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、 “||”、“<<”,“^”等二元操作符的前后应当加空格。 l 一元操作符如“!”、“~”、“++”、“--”、“&”（地址运算符）等前 后不加空格。 C\C++代码编写规范 Ver1.1 １６ l 象“［］”、“.”、“->”这类操作符前后不加空格。 l 对于表达式比较长的 for 语句和 if 语句，为了紧凑起见可以适 当地去掉一些空格，如 for (i=0; i<10; i++)和 if ((a<=b) && (c<=d)) void Func1(int x, int y, int z); // 良好的风格 void Func1 (int x,int y,int z); // 不良的风格 if (year >= 2000) // 良好的风格 if(year>=2000) // 不良的风格 if ((a>=b) && (c<=d)) // 良好的风格 if(a>=b&&c<=d) // 不良的风格 switch (Value) // 良好的风格 switch(Value) // 不良的风格 while (Value) // 良好的风格 while(Value) // 不良的风格 for (i=0; i<10; i++) // 良好的风格 for(i=0;i<10;i++) // 不良的风格 for (i = 0; I < 10; i ++) // 过多的空格 x = a < b ? a : b; // 良好的风格 x=aFunction(); // 不要写成 b -> Function(); C\C++代码编写规范 Ver1.1 １７ § 4.7 其他 § 4.7.1 长行拆分 代码行最大长度宜控制在 70 至 80 个字符以内。表达式要在低优先级 操作符处拆分成新行，操作符放在新行之首（以便突出操作符）。拆 分出的新行要进行适当的缩进，新行的起始位置应该与‘(‘或操作符 之后对齐。使排版整齐，语句可读。如： for (very_longer_initialization; very_longer_condition; very_longer_update) { dosomething(); } if ((very_longer_variable1 >= very_longer_variable12) && (very_longer_variable3 <= very_longer_variable14) && (very_longer_variable5 <= very_longer_variable16)) { dosomething(); } variable = longer_variable12 + longer_variable12 + longer_variable3 + longer_variable4； § 4.7.2 修饰符的位置 修饰符 * 和 ＆ 应该紧靠变量名。 如： char *name; int *x, y; // 此处 y 不会被误解为指针 C\C++代码编写规范 Ver1.1 １８ 附录 A：前缀列表 Type of Variable Prefix of Part 2 Comment BOOL，bool b CHAR, char ch Float f double dbl DWORD dw WORD w HANDLE h Also for HINSTANCE, HWND, and so on. long l int n POINT pnt RECT rect HDC hdc Byte By C\C++代码编写规范 Ver1.1 １９ § 5 图像组的特殊要求 § 5.1 DLL 输出函数 § 5.1.1 参数 所有参数要用 BYTE,WORD,LONG,DOUBLE,VOID*等 当参数为 STRUCT 时,只能传指针,不要传值 § 5.1.2 命名 优先使用 ALLOC,FREE,INIT,EXECUTE,SET,GET,GETRESULT 等单词. § 5.2 内存 基本要求是那里 NEW,那里 DELETE 对于 CLASS 内部的成员变量指针. 构造函树 INIT 化为 NULL.析构函数 TESTDEL.中间先 TESTDEL 再 ALLOC. § 5.2.1 属性的命名 属性的命名不遵循匈牙利命名法，直接使用代表此属性意义的词组。 即：不需要加前缀（限定词+类型缩写）。词义与词义之间用大写字母 区分。如：__declspec(property(get=GetLineSize)) size_t LineSize; § 5.3 层次管理 主流程简单扼要.扇出 4---5 .扇入越多越好.