C语言编程规范（一）

本文简要描述了在使用C语言进行编程活动时，应该遵循的指导原则。主要目标是考虑实际活动中出现的问题以及如何采取可靠的手段以避免这些问题。

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 尽可能在定义变量的同时初始化该变量（就近原则）。