全部博文（346）
分类： C/C++
2008-09-03 16:17:28
软件开发规范
在 研究项目团队协作开发的情况下（这里的团队协作也适合于应用项目的开发），编程时应该强调的一个重要方面是程序的易读性，在保证软件速度等性能指标能满足
用户需求的情况下，能让其他程序员容易读懂你所编写的程序。若研究项目小组的所有开发人员都遵循统一的、鲜明的一套编程风格，可以让协作者、后继者和自己 一目了然，在很短的时间内看清楚程序结构，理解设计的思路，大大提高代码的可读性、可重用性、程序健壮性、可移植性、可维护性。
制定本编程规范的目的是为了提高软件开发效率及所开发软件的可维护性，提高软件的质量。本规范由程序风格、命名规范、注释规范、程序健壮性、可移植性、错误处理以及软件的模块化规范等部分组成。
本软件开发规范适合讨论C/C++程序设计。
1 文件结构
每个C++/C程序通常分为两个文件。一个文件用于保存程序的声明（declaration），称为头文件。另一个文件用于保存程序的实现（implementation），称为定义（definition）文件。
C++/C程序的头文件以“.h”为后缀，C程序的定义文件以“.c”为后缀，C++程序的定义文件通常以“.cpp”为后缀（也有一些系统以“.cc”或“.cxx”为后缀）。
1.1 文件信息声明
文件信息声明位于头文件和定义文件的开头（参见示例1-1），主要内容有：
（1）
版权信息；
（2）
文件名称，项目代码，摘要，参考文献；
（3）
当前版本号，作者/修改者，完成日期；
（4）
版本历史信息；
（5）
主要函数描述。
|
//////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////// // Copyright (c) 2004, Department of Mathematics, // All rights reserved. // // Filename ：filename.h // Project Code ：The
project code about this file // Abstract ：Describe the content of this file summarily // Reference ：...... // // Version ：1.1 // Author ：the name of author(mender) // Accomplished date ： September
2, 2004 // // Replaced version : 1.0 // Original Author : the name of original author(mender) // Accomplished date : September 10, 2003 // // Main functions ： // Function 1 Return code Function
name(Parameter Explain) // Function 2 Return code Function
name(Parameter Explain) // ... // Function n Return code Function
name(Parameter Explain) //////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////// |
|
|
示例1-1 文件信息声明
☆
【规则1.1-1】
文件信息声明以两行斜杠开始，以两行斜杠结束，每一行都以两个斜杠开始；
☆
【规则1.1-2】
文件信息声明包含五个部分，各部分之间以一空行间隔；
☆
【规则1.1-3】
在主要函数部分描述了文件所包含的主要函数的声明信息，如果是头文件，这一部分是可以省略的。
1.2 头文件的结构
头文件由三部分内容组成：
(1) 头文件开头处的文件信息声明(参见示例1-1)；
(2) 预处理块；
(3) 函数和类结构声明等。
假设头文件名称为 filesystem.h，头文件的结构参见示例1-2。
☆
【规则1.2-1】
为了防止头文件被重复引用，应当用ifndef/define/endif结构产生预处理块；“#ifndef”或者“#define”后以TAB键代替SPACE键做空格；如果头文件名称是由多个单词组成，则各单词间以下划线“_”连接，例如有头文件名称为“filesystem.h”，则定义如下：“#ifndef _FILE_SYSTEM_H_”；
☆
【规则1.2-2】
用 #include
☆
【规则1.2-3】
用 #include “filename.h” 格式来引用非标准库的头文件(编译器将从用户的工作目录开始搜索)；
☆
【建议1.2-1】
头文件中只存放“声明”而不存放“定义”；
☆
【建议1.2-1】
头文件中应包含所有定义文件所定义的函数声明，如果一个头文件对应多个定义文件，则不同定义文件内实现的函数要分开声明，并作注释以解释所声明的函数从属于那一个定义文件；
☆
【建议1.2-3】
宏定义和函数声明分离，在两个头文件中定义，如果没有类成员函数，可以将类和结构的定义与函数声明分离，也就是说一个头文件专用于宏定义，一个头文件专用于类和结构的定义，一个头文件专用于函数声明；
☆
【建议1.2-4】 在C++ 语法中，类的成员函数可以在声明的同时被定义，并且自动成为内联函数。这虽然会带来书写上的方便，但却造成了风格不一致，弊大于利。建议将成员函数的定义与声明分开，不论该函数体有多么小。
头文件的结构如下：
|
//文件信息声明见示例1-1，此处省略。 #ifndef _FILE_SYSTEM_H_ //avoid referencing the file filesystem.h
repeat #define _FILE_SYSTEM_H_ #include … #include “myheader.h” //reference non-standard
head file … void Function1(…);
//global function declare … class CBox
//class structure decalre { … }; #endif |
示例1
1.3 定义文件的结构
定义文件有三部分内容：
(1) 定义文件开头处的文件信息声明(参见示例1-1)；
(2) 对一些头文件的引用；
(3) 程序的实现体（包括数据和代码）。
假设定义文件的名称为 filesystem.c，定义文件的结构参见示例1-3。
|
//文件信息声明见示例1-1，此处省略。 #include “filesystem.h” //reference a head
file … //global function realization void Function1(…) { … } //class member function realization void CBox::Draw(…) { … } |
示例1
1.4 头文件的作用
早期的编程语言如Basic、Fortran没有头文件的概念，C++/C语言的初学者虽然会用使用头文件，但常常不明其理。这里对头文件的作用略作解释：
（1） 通过头文件来调用库功能。在很多场合，源代码不便（或不准）向用户公布，只要向用户提供头文件和二进制的库即可。用户只需要按照头文件中的接口声明来调用库功能，而不必关心接口怎么实现的。编译器会从库中提取相应的代码；
（2） 头文件能加强类型安全检查。如果某个接口被实现或被使用时，其方式与头文件中的声明不一致，编译器就会指出错误，这一简单的规则能大大减轻程序员调试、改错的负担。
1.5 目录结构
如果一个软件的头文件数目比较多（如超过十个），通常应将头文件和定义文件分别保存于不同的目录，以便于维护。
例如可将头文件保存于include目录，将定义文件保存于source目录（可以是多级目录）。
如果某些头文件是私有的，它不会被用户的程序直接引用，则没有必要公开其“声明”。为了加强信息隐藏，这些私有的头文件可以和定义文件存放于同一个目录。
2 命名规则
比较著名的命名规则当推“匈牙利” 命名法，该命名规则的主要思想是“在变量和函数名中加入前缀以增进人们对程序的理解”。例如所有的字符变量均以ch为前缀，若是指针变量则追加前缀p。如果一个变量由ppch开头，则表明它是指向字符指针的指针。
“匈牙利”法最大的缺点是烦琐，例如
int i, j, k;
float x, y, z;
倘若采用“匈牙利”命名规则，则应当写成
int iI, iJ, ik; // 前缀 i表示int类型
float fX, fY, fZ; // 前缀 f表示float类型
如此烦琐的程序会让绝大多数程序员无法忍受。
总的说来，没有一种命名规则可以让所有的程序员赞同，且命名规则对软件产品而言并不是“成败悠关”的事，而且在不同的平台和不同的环境下编写的程序所应遵循的规则也不尽相同，所以我们只是追求制定一种令大多数项目成员满意的命名规则，并在项目中贯彻实施。
2.1 共性原则
本节论述的共性规则是被大多数程序员采纳的，我们应当在遵循这些共性规则的前提下，再扩充特定的规则，如2.2节
☆
【规则2.1-1】
标识符应当直观且可以拼读，可望文知意，不必进行“解码”；
☆
【规则2.1-2】
标识符的长度应当符合“min-length &&
max-information”原则；
☆
【规则2.1-3】
命名规则尽量与所采用的操作系统或开发工具的风格保持一致；
☆
【规则2.1-4】
程序中不要出现仅靠大小写区分的相似的标识符。
☆
【规则2.1-5】
程序中不要出现标识符完全相同的局部变量和全局变量，尽管两者的作用域不同而不会发生语法错误，但会使人误解；
☆
【规则2.1-6】
变量的名字应当使用“名词”或者“形容词＋名词”；
☆
【规则2.1-7】
全局函数的名字应当使用“动词”或者“动词＋名词”(动宾词组)；
☆
【规则2.1-8】
用正确的反义词组命名具有互斥意义的变量或相反动作的函数等；
☆
【建议2.1-1】
尽量避免名字中出现数字编号，如Value1,Value2等，除非逻辑上的确需要编号；
注：
2.2 Windows变量命名规则
☆
【规则2.2-1】
变量的命名规则要求采用“匈牙利法则”，即开头字母用变量的类型，其余部分用变量的英文意思或其英文意思的缩写，尽量避免采用中文拼音，要求单词的第一个字母大写；
即：变量名＝变量类型＋变量英文意思(或缩写)
变量类型请参见附表1－变量类型表；
☆
【规则2.2-2】
类名和函数名用大写字母开头的单词组合而成；对struct、union、class变量的命名要求定义的类型用大写，结构采用S开头，联合体采用U开头，类采用C开头；
例如：
struct SPoint
{
int m_nX;
int m_nY;
};
union URecordLen
{
BYTE m_byRecordNum;
BYTE m_byRecordLen;
}
class CNode
{
//类成员变量或成员函数
};
☆ 【规则2.2-3】
指针变量命名的基本原则为：
一重指针变量的基本原则为：
变量名＝ “p”＋变量类型前缀＋命名
对多重指针变量的基本原则为：
二重指针：
变量名＝“pp”＋变量类型前缀＋命名
三重指针：
变量名＝“ppp”＋变量类型前缀＋命名
......
例如一个short*型的变量应该表示为pnStart；
☆ 【规则2.2-4】
全局变量用g_开头；例如一个全局的长型变量定义为g_lFileNum，
即：变量名＝g_＋变量类型＋变量的英文意思(或缩写)；
☆ 【规则2.2-5】
静态变量采用s_开头；例如一个静态的指针变量定义为s_plPrevInst，
即：变量名＝s_＋变量类型＋变量的英文意思(或缩写)；
☆ 【规则2.2-6】 类成员变量采用m_开头；例如一个长型成员变量定义为m_lCount，
即：变量名＝m_＋变量类型＋变量的英文意思(或缩写)；
☆
【规则2.2-7】 对const的变量要求在变量的命名规则前加入c_(若作为函数的输入参数，可以不加)，
即：变量名＝c_＋变量命名规则，例如：
const char* c_szFileName；
☆
【规则2.2-8】
对枚举类型(enum)中的变量，要求用枚举变量或其缩写做前缀，且用下划线隔离变量名，所有枚举类型都要用大写，例如：
enum
EMDAYS
{
EMDAYS_MONDAY;
EMDAYS_TUESDAY;
......
}；
☆
【规则2.2-9】
对常量(包括错误的编码)命名，要求常量名用大写，常量名用英文意思表示其意思，用下划线分割单词，例如：
#define
CM_7816_OK 0x9000；
☆
【规则2.2-10】
为了防止某一软件库中的一些标识符和其它软件库中的冲突，可以为各种标识符加上能反映软件性质的前缀。例如三维图形标准OpenGL的所有库函数均以gl开头，所有常量（或宏定义）均以GL开头。
3 程序风格
程序风格虽然不会影响程序的功能，但会影响程序的可读性，追求清晰、美观，是程序风格的重要构成因素。
3.1 空行
空行起着分隔程序段落的作用。空行得体（不过多也不过少）将使程序的布局更加清晰。空行不会浪费内存，虽然打印含有空行的程序是会多消耗一些纸张，但是值得。
☆
【规则3.1-1】
在每个类声明之后、每个函数定义结束之后都要加空行。参见示例3.1(a)；
☆
【规则3.1-2】
在一个函数体内，逻揖上密切相关的语句之间不加空行，其它地方应加空行分隔。参见示例3.1(b)；
|
// blank line void Function1(…) { … } // blank line void Function2(…) { … } // blank line void Function3(…) { … } |
// blank line while
(condition) {
statement1;
// blank line
if (condition)
{
statement2;
}
else
{
statement3;
} // blank line
statement4; }
|
示例3.1(a) 函数之间的空行
示例3.1(b) 函数内部的空行
3.2 代码行
☆
【规则3.2-1】
一行代码只做一件事情，如只定义一个变量，或只写一条语句,这样的代码容易阅读，并且方便于写注释；
☆
【规则3.2-2】
if、for、while、do等语句自占一行，执行语句不得紧跟其后，不论执行语句有多少都要加{}，这样可以防止书写失误；
☆
【规则3.2-3】 if、for、while、do等语句的“{”要单独占用一行；
☆
【建议3.2-1】
所有函数内的变量都在函数开始处定义；
☆
【建议3.2-2】
尽可能在定义变量的同时初始化该变量(就近原则)，如果变量的引用处和其定义处相隔比较远，变量的初始化很容易被忘记。如果引用了未被初始化的变量，可能会导致程序错误，本建议可以减少隐患。
示例3.2(a)为风格良好的代码行，示例3.2(b)为风格不良的代码行。
|
int nWidth; // width int nHeight; // height int nDepth; // depth |
int nWidth,nHight,nDepth;//width,height,depth |
|
x = a + b; y = c + d; z = e + f; |
X ＝ a + b; y = c +
d; z = e + f; |
|
if (nWidth < nHight) { DoSomething(); } |
if (nWidth < nHight) DoSomething(); |
|
for (initialization; condition; update) { DoSomething(); } // blank line Other(); |
for (initialization; condition; update) DoSomething(); Other(); |
示例3.2(a) 风格良好的代码行
示例3.2(b) 风格不良的代码行
3.3 代码行内的空格
☆
【规则3.3-1】
关键字之后要留空格，象const、virtual、inline、case 等关键字之后至少要留一个空格，否则无法辨析关键字，象if、for、while等关键字之后应留一个空格再跟左括号‘（’，以突出关键字；
☆
【规则3.3-2】
函数名之后不要留空格，紧跟左括号‘（’，以与关键字区别；
☆
【规则3.3-3】
‘（’向后紧跟，‘）’、‘，’、‘;’向前紧跟，紧跟处不留空格；
☆
【规则3.3-4】
‘，’之后要留空格，如Function(x, y, z)，如果‘;’不是一行的结束符号，其后要留空格，如for (initialization;
condition; update)；
☆
【规则3.3-5】
赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、“||”、“<<”,“^”等二元操作符的前后应当加空格；
☆
【规则3.3-6】
一元操作符如“!”、“~”、“++”、“--”、“&”（地址运算符）等前后不加空格；
☆
【规则3.3-7】
象“［］”、“.”、“->”这类操作符前后不加空格；
☆
【建议3.3-1】
对于表达式比较长的for语句和if语句，为了紧凑起见可以适当地去掉一些空格，如for (i=0; i<10;
i++)和if ((a<=b) && (c<=d))
|
void Func1(int x, int y, int
z); // favorable style void Func1 (int x,int y,int
z); // ill style |
|
if (year >=
2000)
// favorable style if(year>=2000)
// ill style if ((a>=b) &&
(c<=d))
// favorable style if(a>=b&&c<=d)
// ill style |
|
for (i=0; i<10;
i++)
// favorable style for(i=0;i<10;i++)
// ill style for (i = 0; I < 10; i
++)
// favorable style |
|
x = a < b ? a :
b;
// favorable style x=a |
|
int *x =
&y;
// favorable style int * x = &
y;
// ill style |
|
array[5] = 0;
// Do not use array [ 5 ] = 0; a.Function();
//
Do not use a . Function(); b->Function();
// Do not use b -> Function(); |
示例3.3 代码行内的空格
3.4 对齐
☆
【规则3.4-1】
程序的分界符‘{’和‘}’应独占一行并且位于同一列，同时与引用它们的语句左对齐；
☆
【规则3.4-2】
{ }之内的代码块在‘{’右边数格处左对齐；
☆
【规则
示例3.4(a)为风格良好的对齐，示例3.4(b)为风格不良的对齐。
|
void Function(int x) { … // program code } |
void Function(int x){ … // program code } |
|
if (condition) { … // program code } else { … // program code } |
if (condition){ … // program code } else { … // program code } |
|
for (initialization; condition; update) { … // program code } |
for (initialization; condition; update){ … // program code } |
|
While (condition) { … // program code } |
while (condition){ … // program code } |
|
如果出现嵌套的｛｝，则使用缩进对齐，如： { … { … } … } |
|
示例3.4(a) 风格良好的对齐
示例3.4(b) 风格不良的对齐
3.5 长行拆分
☆
【规则3.5-1】
代码行最大长度宜控制在70至80个字符以内；
☆
【规则3.5-2】
长表达式要在低优先级操作符处拆分成新行，操作符放在新行之首（以便突出操作符），拆分出的新行要进行适当的缩进，使排版整齐，语句可读。
|
if ((very_longer_variable1 >= very_longer_variable12) && (very_longer_variable3 <=
very_longer_variable14) && (very_longer_variable5 <=
very_longer_variable16)) { DoSomething(); } |
|
virtual CMatrix CMultiplyMatrix (CMatrix leftMatrix,
CMatrix rightMatrix); |
|
for (very_longer_initialization; very_longer_condition; very_longer_update) { DoSomething(); } |
示例3.5 长行的拆分
3.6 修饰符的位置
修饰符 * 和 ＆ 应该靠近数据类型还是该靠近变量名，是个有争议的活题，若将修饰符 * 靠近数据类型，例如：int* x; 从语义上讲此写法比较直观，即x是int 类型的指针，上述写法的弊端是容易引起误解，例如：int* x, y; 此处y容易被误解为指针变量。虽然将x和y分行定义可以避免误解，但并不是人人都愿意这样做。
☆
【规则3.6-1】
应当将修饰符 * 和 ＆ 紧靠变量名；
3.7 注释
C语言的注释符为“/*…*/”。C++语言中，程序块的注释常采用“/*…*/”，行注释一般采用“//…”。注释通常用于：
（1）版本、版权声明；
（2）函数接口说明；
（3）重要的代码行或段落提示。
虽然注释有助于理解代码，但注意不可过多地使用注释。参见示例3.7。
☆
【规则3.7-1】
注释是对代码的“提示”，而不是文档，程序中的注释不可喧宾夺主，注释太多了会让人眼花缭乱，注释的花样要少；
☆
【规则3.7-2】
如果代码本来就是清楚的，则不必加注释；例如
i++; // i 加
1，多余的注释
☆
【规则3.7-3】
边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性，不再有用的注释要删除；
☆
【规则3.7-4】
注释应当准确、易懂，防止注释有二义性，错误的注释不但无益反而有害；
☆
【规则3.7-5】
尽量避免在注释中使用缩写，特别是不常用缩写；
☆
【规则3.7-6】
注释的位置应与被描述的代码相邻，可以放在代码的上方或右方，不可放在下方；
☆
【规则3.7-8】
当代码比较长，特别是有多重嵌套时，应当在一些段落的结束处加注释，便于阅读；
☆
【建议3.7-1】
对于多行代码的注释，尽量不采用“/*...*/”，而采用多行“//”注释，这样虽然麻烦，但是在做屏蔽调试时不用查找配对的“/*...*/”。
|
//////////////////////////////////////////////////////////////////// // Function capacity： // Parameter declare： // Return value ： //////////////////////////////////////////////////////////////////// void Function(float x, float y, float z) { … } |
if (…) { … while (…) { … } // end of while … } // end of if |
示例3.7 程序的注释
文件头的注释请参见1.1，文件头的注释是以两行斜杠开始，以两行斜杠结束(以区别于函数的注释)。
一般说来每个函数都应该做详细的注释，函数头的注释是以一行斜杠开始，以一行斜杠结束，注释的内容包括“功能”，“参数”，“返回值”，“设计思想”，“调用函数”，“日期”，“修改记录”等几个方面，函数头的注释格式如下：
|
////////////////////////////////////////////////////////////////////////////////////////////// // Function capacity ： Describe the
function capacity // Parameter declare ： // parameter 1： Describe
the function of parameter ( input/output parameter ) // parameter 2： Describe the function
of parameter ( input/output parameter ) // ...... // Return value ： Describe the possible return value // Designed idea ： Describe designed idea about the function // Author ： // Creation date ： Creation date(YY-MM-DD) // Transferred function： List the sub-function in the
function // Modification record： // (一)Mender 1：
Modified date： modified
content ////////////////////////////////////////////////////////////////////////////////////////////// |
