Linux平台软件代码编写规范1.0

Linux平台软件代码编写规范(仅供内部使用)文档作者：日期：2008.4.1 说明书校对：日期：项目经理：日期：版权所有不得复制版本修改记录目录1 概述 (4)1.1编写目的 (4)1.2主要内容 (4)1.3创建原则 (4)1.4适用范围 (4)1.5参考资料 (5)1.6术语和缩写词 (5)2 版本控制 (5)3 文件及其组织 (5)3.1文件分类及管理 (5)3.2文件命名 (6)3.3文件结构 (6)3.3.1“.c”、“.cpp”文件 (6)3.3.2“.h”头文件 (7)4 函数 (7)4.1函数书写规范 (7)4.2函数的局部变量和参数 (8)4.3函数的返回值 (8)4.4函数命名规则 (9)4.5函数的设计 (9)5 变量及语句 (9)5.1命名规则 (9)5.1.1变量 (9)5.1.2宏、常量、枚举类型 (9)5.2书写规范 (10)5.2.1缩进 (10)5.2.2行宽 (10)5.2.3括号的位置 (10)5.3编码规则 (11)5.3.1全局变量 (11)5.3.2宏 (11)6 注释 (11)7 测试与调试 (12)8 文档 (12)8.1文档结构 (13)8.2开发文档 (13)1 概述1.1 编写目的为了统一规范公司的代码书写风格，使软件开发工程师能够比较容易的参考、查阅其他工程师开发的代码，也为了使软件项目的管理具有统一性、风格一致性，要求所有相关软件工程师都按照本规范的规定编写和开发软件。

1.2 主要内容本规范主要描述了Linux平台下软件编写所遵循的规范，比较详细的叙述了软件编写过程中的种种要求。

本规范从软件的架构要求、文件的分类、每个文件的格式、每个函数的定义格式、每个变量的定义等等方面规范了软件的书写。

详细内容见后面的相关章节。

1.3 创建原则本规范的制定本着方便实用的原则，从整体上对软件的书写格式加以规范；同时为了方便内部软件交流，又对部分细节加以约束，希望所有相关软件人员都按照此规范严格执行。

当然，随着沟通的加深和项目的深入，本规范难免会有不适用的地方，同时也可能会产生新的要求，这些会随着后续开发的需要，不断加以修正。

1.4 适用范围本规范适用于全部Linux平台下的软件开发项目，包括该平台下的驱动等底层开发和应用程序开发，并适用于所有参与相关项目的软件工程师。

本规范目前从C语言程序设计角度建立该规范，对于其他语言请参考执行。

本规范仅对自行开发的代码加以约束，对API、系统调用、GNU库等无约束力。

1.5 参考资料《Linux kernel coding style》1.6 术语和缩写词略2 版本控制Linux软件项目的全部代码采用SVN服务器做版本控制，每个提交到SVN服务器的代码必须经过本地测试，并符合如下原则：1）能够编译通过，不影响他人编译；2）模块功能确保基本正确，相应结构完整，无明显bug；3）无垃圾代码；4）文件结构清晰，注释清楚；5）满足本规范规定的全部要求。

同时，开发人员在将代码提交到服务器之前，必须在代码所在文件内填写相应的修改记录，同时在上传时填写该修订版本的增量修改日志，便于日后查询。

所有人员的开发工作除非在软件出现重大bug，必须将代码回溯到较旧版本外，一般均要求全部开发必须基于最新版本完成，并提交代码。

在出现需要回溯软件版本情况下，必须及时与项目经理沟通确认，并通知其他开发人员，避免由此造成的任何严重后果。

SVN使用方法请参考其他文档。

本文档不再详述。

3 文件及其组织3.1 文件分类及管理对于linux平台下的软件开发，通常包括如下几类文件：对于项目中出现的文件，必须严格采用上述扩展名命名机制对源代码加以区分。

3.2 文件命名1）项目中出现的全部文件按照功能模块来划分。

不论可能出现的文件的大小，每个模块都以一个“.c ”文件的形式出现，命名为“模块名.c ”，以下简称为“.c ”文件；2）每个“.c ”文件，必然有相同名字命名的“.h ”文件。

“.h ”文件的名字与对应“.c ”文件同名，即“模块名.h ”，以下简称为“.h ”文件。

“.h ”文件的内容，一是定义本模块用到的相应的数据结构。

二是将对应的.c 文件的函数作声明，确保他人在调用该模块相应函数或功能时只需要包含对应模块的“.h ”文件即可。

3) 特殊情况：对于多个模块都需要使用的一些关键变量，比如说，定义显示语言的变量、日志信息的定义等，为了方便后来的修改，可以单独建一个.h 全局变量头文件3.3 文件结构3.3.1 “.c ”、“.cpp ”文件“.c ” 、“.cpp ”文件主要分为文件描述，全局变量声明、本文件范围内的变量的声明、函数的实现几个部分。

“.c ” 、“.cpp ”文件以文件描述开始，内容包含该文件的作者，主要功能，修改记录等等，需要使用注释符分行显示，格式如下图所示：其它各部分的前面都要加上一段/********* XXXXXXX ********/作为开始头，其中，XXX 表示后面的代码的部分的内容，例如：global variables ，local variables ，functions 。

示例如下：3.3.2 “.h ”头文件“.h ”文件与“.c ”文件的书写要求基本相同，包括文件描述、头文件包含、变量声明、数据结构定义、宏定义、函数声明等等。

但是除此之外，为了避免头文件重复包含导致编译出错，要求，每个“.h ”文件必须以#ifndef XXXX 开始，后面马上跟上 #define XXXX ，并且整个文件文件以 #endif 结束，其中XXXX 定义为该文件名的大写后加“_H ”，示例如下：关于函数声明部分应包含该模块全部函数，并将其区分为模块内部函数和模块接口函数两类分开声明，并通过static 和extern 关键字显示加以区别。

4 函数4.1 函数书写规范每个函数前面都必须有一段留给注释的空间，注释头结构如下图所示：注释的内容包括：该函数的功能，输入参数的意义、函数返回不同值的不同含义解释、该函数使用时需要注意的事项。

函数一般从第0列开始书写，函数体的大括号也从第0列写起，并独占一行，函数的具体内容即函数体，使用制表符“TAB”键加以缩进，通常为8个占位符。

该缩进的目的是清晰地标识出一个控制块的起始。

必须严格遵守。

每个函数中的代码分成三部分，第一、变量定义部分，第二、变量初始化部分，第三、函数功能实现部分。

这三个部分之间需要使用一个空白行隔开。

所有该函数中使用的变量都在变量定义部分定义完成，也就是说，函数功能实现部分，没有变量定义的语句，但对具有特殊用途的变量可在程序块中定义，如调试代码所临时使用的变量等。

4.2 函数的局部变量和参数函数的局部变量和参数的数目应尽量少，一般局部变量不应超过10个，参数不应超过5个，否则一定是设计有问题了。

当函数的局部变量和参数过多时，将使函数阅读起来异常困难。

一般，在传递的参数过多时，通常需采用将描述同类事情的变量组合成一个单一的数据结构，进行传递。

4.3 函数的返回值每个函数的返回类型，如果是需要制定的结构体或者变量的话，按照制定的来，否则，使用int型作为返回值类型。

严禁设定void类型返回值的函数。

默认规则，返回负数表示错误，返回0表示成功。

4.4 函数命名规则1）采用英文小写单词，单词与单词之间使用下划线“_”连接2）命名格式如下：返回值类型模块名称_功能简述(参数1,参数2…….);。

这样做，有两个目的：一是方便知道这个函数是在什么模块中定义的，将来给别人看的时候，方便阅读代码。

二是，避免了相似功能的函数的重复定义，避免函数的重名。

3）函数名称中，功能描述部分，一般采用动词在前，名词在后的命名原则，并且尽量简短，但同时要保证对函数功能具有很强的描述性。

如：一个用于对活跃用户进行计数的函数，应该命名为“count_active_users()”，而不是“cntusr()”。

4.5 函数的设计在一个模块中难免要建立多个函数完成其功能，应保证函数体尽量短小，每个函数只实现一个功能。

如果单个函数代码量过大，函数将难以阅读。

当然，如果仅是包含一个很长并很简单的switch-case语句的函数，并且对许多case 做一些很少的操作，那么这个函数长点也没有关系。

但是，如果是一个复杂的函数，则建议按其功能分割为多个函数，如果函数调度所参数的开销在性能上无法满足需求时需采用in-line函数分割该函数。

对于仅模块内部使用的函数使用关键字static加以声明。

5 变量及语句5.1 命名规则5.1.1变量1）变量命名应该能够显示表示该变量的含义，由多个单词构成时单词与单词之间以下划线“_”连接，均采用小写拼写方式；2）全局变量的命名采用“g_”作为开始，以区别于普通变量；3）类名、变量名应以名词结尾；4）名称长度不要很长，要简明扼要，能说明变量的功能、用途。

必要的时候，可以简写，但简写一定要保证该简写方式具有通用含义，如tmp、i(比loop_counter好很多）等。

5.1.2宏、常量、枚举类型1）宏、常量、枚举类型命名应能显示表示其含义，由多个单词组成时，单词与单词之间用下划线“_”分割，单词采用大写英文字符；#define CONSTANT 0x123452）对于功能类似于函数的宏可以使用小写，但不推荐，一般应将其写成内联函数形式。

5.2 书写规范5.2.1缩进1)所有代码必须严格使用缩进机制显示代码的层次关系。

同一层次代码必须具有相同的缩进量；2)缩进的目的是为了清晰地标识代码的层次关系。

必须严格遵守；3)缩进采用制表符“TAB”键，采用8个占位符。

5.2.2行宽由于Linux终端显示行的字符宽度通常较小，因此，行的长度应该限制在80字符以内。

如果一条语句超过了80个字符，应该将它分成多行，每一个子行的长度都不应该超过父行，并且子行应该相对于父行进行充分的向右缩进。

这条规则同样适用于函数参数列表。

过长的字符串也应该被分割成多个较短的字符串。

如下图所示：5.2.3括号的位置1）函数的大括号位置可参考4.1节中函数的书写规范；2）独立的程序块的大括号的位置为左右括号各占单独的一行，括号列位置为同层代码的缩进位置，括号体内要再缩进8个占位符；3）控制块的左括号放在一行的最后，而把右括号放在一行的开始，如下所示：do语句中的"while"或者if语句中的"else"，如下所示：5.3 编码规则5.3.1全局变量全局变量只有在真正需要时才使用,应尽量避免过多的全局变量数目。

5.3.2宏1）有多行语句的宏应该包含在一个do-while块内，如下所示：2）以宏方式定义的常量表达式及其参数应该包含在括号内。