1. 应用范围
本编程规范适用于利用Visual C++ ,Borland C++进行软件程序开发的人员。
2. 设计模块和函数
2.1 创建具有很强内聚力的模块
函数的重要性往往比模块的重要性更容易理解,函数是指执行一个功能的一段代码。模块常被错误的视为是一个仅仅用于存放函数的容器。有些开发人员甚至把这种思路作了进一步的发挥,将他们的所有函数放入单个模块之中。
之所以不能正确的认识模块的功能,原因之一是模块的实现实际上并不影响程序的执行。当一个工程被编译时,如果所有函数都放在单个模块中或者放在几十个模块中,这没有任何关系。虽然模块的数量对代码的执行并无太大的影响,但是当创建便于调试和维护的代码时,模块的数量有时会带来很大的影响。
模块应该用来将相关的函数组织在一起。
当模块包含一组紧密关联的函数时,该模块可以说具有强大的内聚力。当模块包含许多互不相关的函数时,该模块便具有较弱的内聚力。应该努力创建内聚力比较强的模块。
大多数工程都包含许多并不十分适合与其他函数组合在一起的函数。在这种情况下,可以为这些不合群的函数创建一个综合性收容模块。
创建模块时,应知道“模块化”这个术语的含义是什么。模块的基本目的是创建相当独立的程序单元。从根本上来讲,模块可以添加给另一个工程,并且可以通过直接调用它的公用函数来使用它。
2.2 创建松散连接和高度专用的函数
1. 使所有函数都执行专门的任务
每个函数都应执行一项特定的任务,它应出色的完成这项任务。应避免创建执行许多不同任务的函数。
创建专用函数有许多好处。首先调试将变得更加容易。
2. 尽量使函数成为自成一体的独立函数
当一个函数依赖于其他函数的函数时,称为与其他函数紧密连接的函数。紧密连接的函数会使调试和修改变得比较困难,因为它牵涉到更多的因素。松散连接的函数优于紧密连接的函数,但你不可能使每个函数都成为独立的函数。
若要使函数具备较强的独立性,方法之一是尽量减少全局变量和模块级变量。
创建函数时,设法将每个函数视为一个黑箱,其他函数不应要求了解该函数的内部工作情况,该函数也不应要求了解它外面的工程情况。这就是为什么你的函数应依靠参数而不应依靠全局变量的原因。
创建专用函数时,请考虑下列指导原则:
1) 将复杂函数放入专用函数。如果应用程序使用复杂的数学公式,请考虑将每个公式放入它自己的函数中。这样使用这些公式的其他函数就不包含用于该公式的实际代码。这样也可以更容易发现与公式相关的问题。
2) 将数据输入/输出(I/O)放入专用函数。
3) 将专用函数中可能要修改的代码隔离。如果你知道某个进程经常变更,请将这个多变的代码放入专用函数,以便以后可以更容易的进行修改,并减少无意中给其他进程带来问题的可能性。
4) 将业务规则封装在专用函数中。业务规则常属于要修改的代码类别,应与应用程序的其余部分隔开。其他函数不应知道业务规则,只有要调用的函数才使用这些规则。
3. 设计模块和函数时,要达到下列目的:
1) 创建更加容易调试和维护的函数
2) 创建具有强大内聚力的模块
3) 创建高度专用的函数
4) 创建松散连接的函数
5) 尽量使函数具有独立性
6) 提高函数的扇入性
7) 降低函数的扇出性
2.3 编程原则
1. 为函数和模块赋予表义性强的名字
为了使代码更加容易理解,最容易的方法之一是为你的函数赋予表义性强的名字。函数名DoIt、GetIt的可读性很难与CalculateSalesTax、 RetrieveUserID相比。
由缩写函数名组成的代码很难理解和维护,没有理由再这样做了。
给函数正确的命名,可使程序工程的调试和维护工作大大的改观。请认真对待函数命名的工作,不要为了减少键入操作量而降低函数的可理解度。
实际应用举例:
1) 给函数命名时应大小写字母混合使用。如果句子全使用大写字母,那么阅读起来就非常困难,而大小写字母混合使用的句子,阅读起来就很容易。
2) 定义函数名时不要使用缩写。如果你认为应用程序中的某些工程应使用缩写,那么请将这些情况加上注释,并确保每个人在所有时间内都使用这些缩写。决不要在某些函数中对某些单词进行缩写,而在别的函数中却不使用缩写。
2. 为每个函数赋予单个退出点
3. 创建函数程时,始终都应显式地定义它的作用域。
1) 如果你真的想创建一个公用函数,请向代码阅读者说明这一点。
2) 通过为每个函数赋予一个明确定义的作用域,可以减少代码阅读者需要投入的工作量。应确保你为函数赋予最有意义的作用域。如果一个函数只被同一模块中的另一个函数调用,那么请将它创建成专用函数。如果该函数是从多个模块中的多个函数中调用,请将该说明为公用函数。
4. 用参数在函数之间传递数据
应尽量避免使用模块级变量。一般来说,变量的作用域越小越好。为了减少模块级变量和全局变量,方法之一是将数据作为参数在不同函数之间传递,而不是让函数共享模块级变量或全局变量。
1) 为每个参数指定数据类型。
2)
3) 始终要对数进行检验,决不要假设你得数据没有问题。程序员常犯的一个错误是在编写函数时假设数据没有问题。在初始编程阶段,当编写调用函数时,这样的假设并无大碍。这时你完全能够知道什么是参数的许可值,并按要求提供这些值。但如果你不对参数的数据进行检验,那么下列情况就会给你带来很大麻烦:另外某个人创建了一个调用函数,但此人不知道允许的值;你在晚些时候添加了新的调用函数,并错误的传递了坏数据。
4) 当参数只接受较小的一组值时,请使用枚举值。使用枚举值,可降低编码时出现数据输入错误的可能性。只要有可能,就可考虑使用枚举值。
3. 命名约定
所有变量的定义应该遵循匈牙利命名法,它使用3字符前缀来表示数据类型,3个字符的前缀必须小写,前缀后面是由表意性强的一个单词或多个单词组成的名字,而且每个单词的首写字母大写,其它字母小写,这样保证了对变量名能够进行正确的断句。
这样,在一个变量名就可以反映出变量类型和变量所存储的值的意义两方面内容,这使得代码语句可读性强、更加容易理解。
3.1 结构
结构体类型命名必须全部用大写字母,结构体变量命名必须用大小写字母组合,第一个字母必须使用大写字母,必要时可用下划线间隔。对于私有数据区,必须注明其所属的进程。全局数据定义只需注意其用途。
示例如下:
typedef struct
{
char szProductName[20];
char szAuthor[20];
char szReleaseDate[16];
char szVersion[10];
unsigned long MaxTables;
unsigned long UsedTables;
}DBS_DATABASE;
DBS_DATABASE GdataBase;
3.2 宏定义
宏定义必须具有一定的实际意义;
宏定义在#include和函数定义之间;
宏定义必须全部以大写字母来撰写,中间可根据意义的连续性用下划线连接,每一条定义的右侧必须有一简单的注释,说明其作用;
3.3 资源名定义
资源名 命名方式
菜单 IDM_XX
位图 IDB_XX
对话框 IDD_XX
字符串 IDS_XX
DLGINIT DIALOG_XX
ICON IDR_XX
3.4 函数命名
函数原型说明包括引用外来函数及内部函数,外部引用必须在右侧注明函数来源:模块名及文件名, 如是内部函数,只要注释其定义文件名;
第一个字母必须使用大写字母,要求用大小写字母组合规范函数命名,必要时可用下划线间隔,示例如下:
void UpdateDB_Tfgd (TRACK_NAME); //Module Name :r01/sdw.c
void PrintTrackData (TRACK_NAME); //Module Name :r04/tern.c
void ImportantPoint (void); //Module Name :r01/sdw.c
void ShowChar (int , int , chtype); //Local Module
void ScrollUp_V (int , int); //Local Module
3.5 其它
开发人员如果遇到上述表格中未列举的类型,请书面通知相关管理人员,由管理人员集中更新列表内容,不得擅自启用未经确定的新变量或控件前缀。
4. 使用常量和枚举值
4.1 使用常量
1. 常数很容易在数据输入时出错
常数存在的主要问题之一是你很容易在键入数字时出错,从而颠倒了数字的位置。例如,当你键入数字10876时,很容易的键入10867或18076。与处理变量和保留字的方法不同,编译器并不在乎颠倒了位置和不正确的数字,有时简单的错误造成的问题不会立即表现出来,而当问题表现出来时,它们会以随机的计算错误的形式出现,这些错误很难准确定位。用常量来取代常数时,在编译时检查常量的有效性。如果常量不存在,编译器便将这一情况通知你,并拒绝进行编译,这可以消除错误键入的数字带来的问题,只要常量拥有正确的值,使用该常量的所有代码也有使用该正确值。
2. 常数很难不断更新
3. 常量使代码更容易阅读
使用常量后,得到的一个额外好处是可使创建的代码更容易阅读。常数很不直观。也许你对常数非常了解,但其他人则根本看不明白。通过合理的给常量命名,使用这些常量的代码就变得比较直观了,更容易阅读。
为常量赋予较宽的作用域,这与使用变量时的情况不同。在一个应用程序中你决不应该两次创建相同的常量。如果你发现自己复制了一个常量,请将原始的常量说明转至较宽的作用域,直到该常量可供引用它的所有函数为止。
4.2 使用枚举值
你不必记住参数的数值,错误地设定值的可能性也大大减少了。虽然你仍可为参数设定数值,而不是设定枚举成员的名字,但你决不应该这样去做。
1. 枚举值的所有成员都是长整型数,你不得使用其他数据类型。
2. 使用常量和枚举值的目的:
减少数字换位和键入错误带来的代码错误;
将来可以更容易更改各个值;
使代码更容易阅读。
4.3 编程原则
常量不同于变量的另一个标识特征是不使用数据类型前缀。
有些外部数据库仍然使用大写字母常量。例如,如果用 API浏览器查找和拷贝与API相关的常量,你常可看到它们是使用大写字母的常量。在这种情况下,请将这些常量保持原状,以便达成应用程序之间的一致性。
1. 将应用程序前缀或特定的前缀用于枚举成员
不必用前缀来表示枚举成员的类型,因为所有成员总是属于长整型数。但应该使用专门的前缀来表示它的值来自应用程序或组件。
应该用一个指示符作为枚举成员的前缀,因为当编译器遇到一个枚举成员名时,如果其他被引用的类型库中包含相同的名字,它就会搞混。
2. 当参数接受有限数量的值时,请使用枚举
3. 使用switch结构时,始终要加上一个default子句,以便处理传递给函数的有效值。
5. 变量
5.1 定义有焦点的变量
用于多个目的的变量称为无焦点(多焦点)的变量。无焦点变量所代表的意义与程序的执行流程有关,当程序处于不同位置时,它所表示的意义是不固定的,这样就给程序的可读性和可维护性带来了麻烦。
5.2 只对常用变量名和长变量名进行缩写
如果需要对变量名进行缩写时,一定要注意整个代码中缩写规则的一致性。例如,如果在代码的某些区域中使用Cnt,而在另一些区域中又使用Count,就会给代码增加不必要的复杂性。
变量名中尽量不要出现缩写。
5.3 使用统一的量词
通过在结尾处放置一个量词,就可创建更加统一的变量,它们更容易理解,也更容易搜索。例如,请使用strCustomerFirst和strCustomerLast,而不要使用strFirstCustomer和strLastCustomer。
量词列表:
量词后缀 说明
First 一组变量中的第一个
Last 一组变量中的最后一个
Next 一组变量中的下一个变量
Prev 一组变量中的上一个
Cur 一组变量中的当前变量
5.4 使用肯定形式的布尔变量
给布尔变量命名时,始终都要使用变量的肯定形式,以减少其它开发人员在理解布尔变量所代表的意义时的难度。
5.5 为每个变量选择最佳的数据类型
这样即能减少对内存的需求量,加快代码的执行速度,又会降低出错的可能性。用于变量的数据类型可能会影响该变量进行计算所产生的结果。在这种情况下,编译器不会产生运行期错误,它只是迫使该值符合数据类型的要求。这类问题极难查找。
5.6 尽量缩小变量的作用域
如果变量的作用域大于它应有的范围,变量可继续存在,并且在不再需要该变量后的很长时间内仍然占用资源。
它们的主要问题是,任何模块中的任何函数都能对它们进行修改,并且很难跟踪究竟是何处进行修改的。
占用资源是作用域涉及的一个重要问题。如果创建全局的Recordset(记录集)变量,问题会复杂。对于Recordset
对变量来说,尽量缩小作用域将会对应用程序的可靠性产生巨大的影响。
6. 代码的格式化
6.1 对代码进行格式化时,要达到的目的
1. 通过代码分割成功能块和便于理解的代码段,使代码更容易阅读和理解;
2. 使用空行和注释行,将程序中逻辑上不相关的代码块分开。比如:变量声明部分和代码语句间的分隔;较长的函数中,完成不同功能的代码块间的分隔。要避免出现逻辑上混乱的分隔,如:某一逻辑功能代码块中间用空行进行了分隔,但是在相邻功能代码块之间却没有分隔,这样会给程序阅读者造成错觉。
3. 减少为理解代码结构而需要做的工作;
4. 使代码的阅读者不必进行假设;
5. 使代码结构尽可能做到格式清楚明了。
6.2 编程原则
1. 要将多个语句放在同一行上
不论是变量声明,还是语句都不要在一行上书写多个。
2. 缩进后续行
当你将变量设置为某个值时,所有后续行的缩进位置应与第一行的变量值相同;
当你调用一个函数时,后续行缩进到第一个参数的开始处;
当你将变量或属性设置为等于表达式的计算结果时,请从后面分割该语句,以确保该表达式尽可能放在同一行上。
3. 在if语句后缩进;
在else语句后缩进
在switch语句后缩进
在case语句后缩进
在do语句后缩进
已经用行接续符分割的语句的各个行要缩进。
对从属于行标注的代码进行缩进。
4. 在执行统一任务的各个语句组之间插入一个空行。好的代码应由按逻辑顺序排列的进程或相关语句组构成。
7. 代码的注释
7.1 使用代码注释的目的
1. 文字说明代码的作用(即为什么要用编写该代码,而不是如何编写);
2. 确指出该代码的编写思路和逻辑方法;
3. 人们注意到代码中的重要转折点;
4. 使代码的阅读者不必在他们的头脑中仿真运行代码的执行函数.
7.2 编程原则
1. 用文字说明代码的作用:
简单的重复代码做写什么,这样的注释几乎不能给注释增加什么信息.如果你使用好的命名方法来创建直观明了的代码那么这些类型的注释绝对增加不了什么信息.
2. 如果你想违背好的编程原则,请说明为什么
有的时候你可能需要违背好的编程原则,或者使用了某些不正规的方法,.遇到这种情况时,请用内部注释来说明你在做什么和为什么要这样做。
技巧性特别高的代码段,一定要加详细的注释,不要让其他开发人员花很长时间来研究一个高技巧但不易理解的程序段。
3. 用注释来说明何时可能出错和为什么出错
4. 在编写代码前进行注释
给代码加注释的方法之一是在编写一个函数前首先写上注释.如果你愿意,可以编写完整句子的注释或伪代码.一旦你用注释对代码进行了概述,就可以在注释之间编写代码.
5. 在要注释的代码前书写注释
注释一定出现在要注释的程序段前,不要在某段程序后书写对这段程序的注释,先看到注释对程序的理解会有一定帮助。
如果有可能,请在注释行与上面代码间加一空行。
6. 纯色字符注释行只用于主要注释
注释中要分隔时,请使用一行空注释行来完成,不要使用纯色字符,以保持版面的整洁、清晰。
7. 避免形成注释框
用星号围成的注释框,右边的星号看起来很好,但它们给注释增加了任何信息吗?实际上这会给编写或编辑注释的人增加许多工作。
8. 使用//来指明注释
9. 增强注释的可读性
注释是供人阅读的,而不是让计算机阅读的。
1) 使用完整的语句。虽然不必将注释分成段落(最好也不要分成段落),但你应尽量将注释写成完整的句子。
2) 避免使用缩写。缩写常使注释更难阅读,人们常用不同的方法对相同的单词进行缩写,这会造成许多混乱,如果必须对词汇缩写,必须做到统一。
3) 将整个单词大写,以突出它们的重要性。若要使人们注意注释中的一个或多个单词,请全部使用大写字母。
10. 对注释进行缩进,使之与后随的语句对齐。
注释通常位于它们要说明的代码的前面。为了从视觉上突出注释与它的代码之间的关系,请将注释缩进,使之与代码处于同一个层次上。
11. 为每个函数赋予一个注释标头
每个函数都应有一个注释标头。函数的注释标头可包含多个文字项,比如输入参数、返回值、原始作者、最后编辑该函数的程序员、上次修改日期、版权信息。
12. 当行尾注释用在上面这种代码段结构中时,它们会使代码更难阅读。
使用多个行尾注释时(比如用于函数顶部的多个变量说明),应使它们互相对齐。这可使它们稍容易阅读一些。
13. 何时书写注释
1) 请在每个if语句的前面加上注释。
2) 在每个switch语句的前面加上注释。与If语句一样,switch语句用于评估对程序执行产生影响的表达式。
3) 在每个循环(包括for循环和do循环)的前面加上注释。每个循环都有它的作用,许多情况下这个作用不清楚直观。
4) 在修改了全局变量的每个语句前面加上注释。全局变量很讨厌。但如果非常需要使用全局变量,请说明你为何要修改它。这将使代码的调试容易一些。
8. 控制代码流
8.1 控制代码流的目的
1. 在规定的情况下使用正确的判断构造;
2. 降低代码的复杂性,使之更容易阅读和调试;
3. 最大限度的减少表达式计算中出错的机会。
8.2 编程原则
1. 当根据一个条件是true还是false来做出判断时,使用If…Else
即使只有一个语句被执行,也应考虑使用{}构造。当condition的计算结果是true时,如果只有一个语句被执行,该语句可以与if放在同一行上,并且{}可以省略。但若要使代码更便于阅读,请将该语句单独放在一行上,并以{}语句的标记。
2. 对非布尔表达式与各种可能的值进行比较时,使用switch语句.
switch可以用许多高档次的方式来使用,比如将多个结果值放在一个case行上。
这些条件互相之间可能毫不相关。这与switch结构完全相反。在switch结构中,通过对一个(通常是非布尔)测试表达式与case语句中的每个表达式进行比较,从而构成了各个条件。
1) 所有case语句都应使用便于理解的顺序。
2) 不要编写决不会产生true结果的case语句。
3. 对表达式进行格式化
对表达式进行正确的格式化可以减少代码出错的可能性,增加代码的可读性。
1) 为了清楚起见,用括号将表达式括起来。即使不要求,也要使用括号。不要书写复杂的依靠运算符优先级来执行的表达式,在必要的位置使用括号强调其运算优先级。
goto标识全部使用大写字母。goto语句使得代码很难阅读。通过将goto标识全部使用大写字母,就可以减少查找程序中的goto标识所需的工作量。