Linux项目组编程规范

前言：

本手册以林锐博士编写的《高质量 C++/C 编程指南》内容为参考，根据项目组成员的经验总结和共同协定，稍作简洁和修改。本规范手册分成两部分：

第一部分：以条款的形式列出了项目组编程的规则和建议，规则是指项目组成员必须要遵守的编程规范，建议是指推荐使用的编程风格。

第二部分：是对第一部分规则和建议的详细说明。建议先仔细阅读第二部分，在已经了解了每条规则和建议的真正意义以及为什么要遵守的基础上，在实际项目编程时可以通过直接查阅第一部分来实现快速规范代码的目的。

本手册由Linux项目组成员共同制定，暂时处于beta版本，由于我们经验有限，对本手册的任何建议和批评都欢迎各位提出，我们将虚心接受。

 

 

 

Linux项目组

2009-4-23

第一部分：

第 1 章 文件结构

【规则 1-1】为了防止头文件被重复引用，应当用 ifndef/define/endif 结构产生预处理块；

【规则1-2】头文件由三部分内容组成：

(1) 头文件开头处的版权和版本声明(参见第二部分示例 1-1)

(2) 预处理块

(3) 函数和类结构声明等

【规则1-3】定义文件由三部分内容组成：

(1) 定义文件开头处的版权和版本声明(参见示例 1-1)。

(2) 对一些头文件的引用

(3) 程序的实现体(包括数据和代码)

【规则1-4】不提倡使用全局变量，尽量不要在头文件中出现象 extern int value 这类声明。

 

【建议 1-5】头文件中只存放“声明”而不存放“定义”。建议将成员函数的定义与声明分开，不论该函数体有多么小；

第 2章 程序的版式

【规则2-1】在每个函数定义结束之后都要加空行；

【规则2-2】在一个函数体内，逻揖上密切相关的语句之间不加空行，其它地方应加空行分隔；

【规则2-3】一行代码只做一件事情，如只定义一个变量，或只写一条语句。这样的代码容易阅读，并且方便于写注释；

【规则2-4】if、for、while 、do 等语句自占一行，执行语句不得紧跟其后。不论执行语句有多少都要加{}。这样可以防止书写失误。程序的分界符‘{’和‘}’应独占一行并且位于同一列，同时与引用它们的语句左对齐；

【规则2-5】‘，’ ‘;’向前紧跟，紧跟处不留空格。 ‘，’之后要留空格，如Function(x, y, z) 。如果‘;’不是一行的结束符号，其后要留空格，如for (initialization; condition; update)；

【规则2-6】赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=”“>=”、“<=”、“+”、“*”、“%”、“&&”、“||”、“<<”,“^”等二元操作符的前后应当加空格；

【规则2-7】一元操作符如“!”、“~”、“++”、“--”、“&”(地址运算符)等前后不加空格；

【规则2-8】像“[]” “.” “->”这类操作符前后不加空格；

【规则2-9】应当将修饰符*和＆紧靠变量；

【规则2-10】如果代码本来就是清楚的，则不必加注释。否则多此一举，令人厌烦。例如i++; // i加1，多余的注释；

【规则2-11】注释的位置应与被描述的代码相邻，可以放在代码的上方或右方，不可放在下方；

【规则2-12】尽可能在定义变量的同时初始化该变量(就近原则)；

 

【建议2-13】代码行最大长度宜控制在70至80个字符以内。代码行不要过长，否则眼睛看不过来，也不便于打印；

【建议2-14】长表达式要在低优先级操作符处拆分成新行，操作符放在新行之首(以便突出操作符)。拆分出的新行要进行适当的缩进，使排版整齐，语句可读；

【建议2-15】注释是对代码的“提示”，而不是文档。程序中的注释不可喧宾夺主，注释太多了会让人眼花缭乱。注释的花样要少；

【建议2-16】边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除；

【建议2-17】注释应当准确、易懂，防止注释有二义性。错误的注释不但无益反而有害；

【建议2-18】尽量避免在注释中使用缩写，特别是不常用缩写；

【建议2-19】当代码比较长，特别是有多重嵌套时，应当在一些段落的结束处加注释，便于阅读。

【建议2-20】对于表达式比较长的for 语句和if 语句，为了紧凑起见可以适当地去掉一些空格，如for (i=0; i<10; i++)和if ((a<=b) && (c<=d)) 。

第 3 章  命名规则

【规则3-1】标识符应当直观且可以拼读，可望文知意，不必进行“解码” 。 标识符最好采用英文单词或其组合，便于记忆和阅读。切忌使用汉语拼音来命名。程序中的英文单词一般不会太复杂，用词应当准确；

【规则3-2】命名规则尽量与所采用的操作系统或开发工具的风格保持一致。 Linux 应用程序的标识符通常采用“小写加下划线”的方式，如 add_child。

【规则3-3】程序中不要出现仅靠大小写区分的相似的标识符；

【规则3-4】程序中不要出现标识符完全相同的局部变量和全局变量，尽管两者的作用域不同而不会发生语法错误，但会使人误解；

【规则3-5】用正确的反义词组命名具有互斥意义的变量或相反动作的函数等；

【规则 3-6】尽量使用含义直观的常量来表示那些将在程序中多次出现的数字或字符串；

【规则 3-7】需要对外公开的常量放在头文件中，不需要对外公开的常量放在定义 文件的头部。为便于管理，可以把不同模块的常量集中存放在一个公共的头文件中；

 

【规则3-8】结构体名和函数名用小写的单词加下划线组合而成，下划线起分隔作用，不要用下划线开头，单词可以适当缩写；

【规则3-9】局部变量，结构体成员和参数用小写字母单词和下划线组合而成；

【规则 3-10】宏，const变量，用户自定义类型名和枚举类型一定得使用大写字母的单词。

 

【规则3-11】静态变量和函数加前缀 s_(表示static)，全局变量如果只在本文件中使用就用static，尽量使用静态全局变量而不要使用全局变量；局部变量不要使用satic修饰；

【规则3-12】如果不得已需要全局变量，则使全局变量加前缀g_(表示global)，并要在头文件中声明；

 

【建议3-13】尽量避免名字中出现数字编号，如 Value1,Va lue2 等，除非逻辑上的确需要编号。这是为了防止程序员偷懒，不肯为命名动脑筋而导致产生无意义的名字(因为用数字编号最省事)。

【建议 3-14】变量的名字应当使用“名词”或者“形容词＋名词” ；

【建议 3-15】全局函数的名字应当使用“动词”或者“动词＋名词” (动宾词组) ；

类的成员函数应当只使用“动词” ，被省略掉的名词就是对象本身；

【建议 3-16】如果某一常量与其它常量密切相关，应在定义中包含这种关系，而不应给出一些孤立的值。

第 4 章表达式和基本语句

【规则4-1】如果代码行中的运算符比较多，用括号确定表达式的操作顺序，避免使用默认的优先级;

【规则4-2】不要编写太复杂的复合表达式;

【规则4-3】不要有多用途的复合表达式;

【规则4-4】不可将布尔变量直接与TRUE、FALSE 或者1、0 进行比较;

【规则4-5】应当将整型变量用“==”或“！=”直接与0 比较;

【规则4-6】不可将浮点变量用“==”或“！=”与任何数字比较;

【规则4-7】应当将指针变量用“==”或“！=”与NULL 比较;

【规则4-8】每个case 语句的结尾不要忘了加break，否则将导致多个分支重叠(除非有意使多个分支重叠，如果是有意的，一定要加上注释);

【规则4-9】不要忘记最后那个default 分支。即使程序真的不需要default 处理，也应该保留语句 default : break; 这样做并非多此一举，而是为了防止别人误以为你忘了default 处理。

 

【建议4-10】在多重循环中，如果有可能，应当将最长的循环放在最内层，最短的循环放在最外层，以减少CPU 跨切循环层的次数；

【建议4-11】如果循环体内存在逻辑判断，并且循环次数很大，宜将逻辑判断移到循环体的外面；

【建议4-12】不可在for 循环体内修改循环变量，防止for 循环失去控制;

【建议4-13】建议for 语句的循环控制变量的取值采用“半开半闭区间”写法。

 

第 5 章 函数设计

【规则5-1】参数的书写要完整，不要贪图省事只写参数的类型而省略参数名字。如果函数没有参数，则用void 填充；

【规则5-2】如果参数是指针，且仅作输入用，则应在类型前加const，以防止该指针在函数体内被意外修改；

【规则5-4】不要省略返回值的类型；

 

【建议5-5】尽量不要使用类型和数目不确定的参数；

【建议5-6】函数名字与返回值类型在语义上不可冲突；

【建议 5-7】不要将正常值和错误标志混在一起返回。正常值用输出参数获得，而错误标志用return 语句返回；

【建议5-8】在函数体的“入口处”，对参数的有效性进行检查；

【建议5-9】在函数体的“出口处”，对return 语句的正确性和效率进行检查。

【建议5-10】函数的功能要单一，不要设计多用途的函数；

【建议5-11】不仅要检查输入参数的有效性，还要检查通过其它途径进入函数体内的变量的有效性，例如全局变量、文件句柄等；

【建议5-12】用于出错处理的返回值一定要清楚，让使用者不容易忽视或误解错误情况。

【建议5-13】避免函数有太多的参数，参数个数尽量控制在5 个以内。如果参数太多，在使用时容易将参数类型或顺序搞错；

【建议 5-14】参数命名要恰当，顺序要合理；