1.介绍

编写规范的目的是为各开发团队提供编程规范的基础和参考，本文档并不是要成为终极编程规范，但是我们希望这些规范可以被广泛的接受。定义编程规范有助于提高开发速度，使得开发人员不需要总是从一些基本原则出发进行决策；有助于增进团队精神；有助于减少在一些小事上不必要的争论；使团队成员更容易阅读和维护其他成员的代码；有助于使开发人员放开手脚，在有意义的方向上发挥创造性。

在压力和时间的要求下，人们将按所受到的训练行事。他们会求助于习惯。作为软件开发人员，我们总是面对着巨大的压力，“要在昨天交付明天的软件”。在进度压力下，我们按所受到的训练和习惯工作。平时不知道培养软件工程良好实践的（或者不习惯应用这些实践的）马虎程序员，在压力下将编写出更加马虎、错误更多的代码。相反，养成良好习惯并经常按此工作的程序员将保持自己的组织性，快速提交高质量的代码的能力。

最后，规则并非一成不变的，欢迎加入来自实际应用中的经验和反馈。

2.文件结构

规则 2-1 一个文件中不要包含超过2000行的代码。

每个C程序通常分为两个文件。一个文件用于保存程序的声明（declaration），称为头文件。另一个文件用于保存程序的实现（implementation），称为定义（definition）。C 程序的头文件以“.h”为后缀，C 程序的定义文件以“. c”为后缀。一个文件中包含超过1000行的代码较难阅读，所以应该按照逻辑功能划分成多个文件。

此规则只适用于源代码

规则 2-2 文件为了防止头文件被重复引用，应当用#ifndef/#define/#endif 结构产生预处理块，建议宏定义为“_+头文件的名字+_H”。

举例：头文件的名称为lun_pub.h,其预处理宏为_LUN_PUB_H。

3.注释

规则 3-1 说明性文件（如.h文件）头部必须包含统一风格的注释。注释中应该包含版权说明、文件名称、功能说明、版本号、作者、日期、修订说明等。

说明：对.h文件注释的示例:

/** *    COPYRIGHT NOTICE *    Copyright (c) 2010, MacroSAN *    All rights reserved. * * @file 	disk_pub.h * 本文件主要定义磁盘子系统公用接口，包含下面几个部分的内容:\n * 			1. 磁盘子系统的对外接口；\n * 			2. 磁盘子系统与其他模块进行数据交互的数据结构；\n * 			3. 磁盘子系统相关的宏定义；\n *	 *	版本	作者		日期			修订说明 * *   1.00     xxx		2010-08-10		最初版本 */

规则 3-2 源文件头部必须包含统一风格的注释。注释中应该包含版权说明、文件名称、功能说明、版本号、作者、日期、修订说明等。

说明：对.c文件注释的示例：

/** *    COPYRIGHT NOTICE *    Copyright (c) 2010, MacroSAN *    All rights reserved. * * @file disk_mgt.c * 本文件主要定义磁盘子系统磁盘管理的对外接口，包括查询磁盘信息、安全拔盘等； * *	版本	作者		日期			修订说明 * *   1.00     xxx		2010-08-10		最初版本 * */

规则 3-3 函数头部必须包含统一风格的注释。注释中应该包含函数的功能、输入参数、输出参数、返回值，函数说明、作者、日期、修订说明、问题单号等。

说明：对函数注释的示例：

/** 通过磁盘的uuid查询磁盘的详细信息 * *	该函数通过查询disk的配置文件来获取磁盘的详细信息，这些信息由struct disk_info_t定义 * * @param[in]disk_uuid 磁盘的uuid * @param[out]disk_info 指定磁盘的详细信息，输出参数 * @return          函数执行成功返回S_OK，否则返回相应的错误码 *  * @note	disk_info为输出参数，在调用本函数时，需要先申请disk_info的内存； * * 作者	日期		问题单号		修订说明		 * * xxx	2010-08-10	未涉及		最初版本		* * xxx	2010-11-29	xxx		增加debug打印；	*/int32_t diskmgt_query_info(uuid_t * disk_uuid, disk_info_t *disk_info){	……}

规则 3-4 对于宏、结构体和枚举代码的注释，需要简要说明其具体的含义，最好自注释的代码。

说明：对宏、结构体和枚举定义的示例：

#define PORT_NUM_PER_SP	2	/**< 每个控制器的最大channel */#define DSU_NUM_PER_CHANNEL	16	/**< 每个channel上接的最大dsu数目 *//** 描述dsu的位置的结构体 * *	DSU的名称格式为：DSU-DSU ID，DSU ID的编号规则是Port ID:DSU Location ID， *	即端口ID:DSU位置编号，DSU位置编号表示DSU级数，从1开始编号 */typedef struct dsu_location{    uint32_t    port_id;    /**< spu的port id*/    uint32_t    dsu_id;     /**< dsu的location id*/}dsu_location_t;

规则 3-5 源代码应该使用/…/ 类型的注释，并且/…./字符序列中不能再包含/*。

C不支持注释的嵌套，尽管一些编译器支持它以做为语言扩展。一段注释以/开头，直到第一个/为止，在这当中出现的任何/*都违反了本规则。示例如下：

/* some comment, end comment marker accidentally omitted<<New Page>>Perform_Critical_Safety_Function (X);/* this comment is not compliant */

在检查包含函数调用的页中，假设它是可执行代码。

建议 3-1 注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达。

注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文。

4.程序版式

规则 4-1 程序块要采用缩进风格编写，缩进的空格数为4个。

说明：对于由开发工具自动生成的代码可以有不一致。

规则 4-2 在每个函数定义结束之后都要加空行。

示例：

// 空行void Function1(.){...}// 空行void Function2(.){...}// 空行

规则 4-3 在一个函数体内，逻辑上密切相关的语句之间不加空行，其它地方应加空行分隔。

示例：

// 空行while (condition){statement1;// 空行if (condition){statement2;}else{statement3;}// 空行statement4;}

规则 4-4 一行代码只做一件事情，如只定义一个变量，或只写一条语句。

规则 4-5 if、for、while、do等语句自占一行，执行语句不得紧跟其后。不论执行语句有多少都要加{}。

规则 4-6 程序块的分界符{}应各独占一行并且位于同一列，同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用缩进方式。

不符合规范的示例：

f

or (...) {... // program code}if (...){... // program code}

符合规范的示例：

for (...){... // program code}if (...){... // program code}

规则 4-7 一行程序以小于80字符为宜，不要写得过长。

规则 4-8 长表达式要在低优先级操作符处拆分成新行，操作符放在新行之首（以便突出操作符）。拆分出的新行要进行适当的缩进，使排版整齐，语句可读。

示例：

if ((very_longer_variable1 >= very_longer_variable12)&& (very_longer_variable3 <= very_longer_variable14)&& (very_longer_variable5 <= very_longer_variable16)){dosomething();}

规则 4-9 尽可能在定义变量的同时初始化该变量（就近原则）。