linux C 语言编程规范.doc

C 语言编程规范1 序言.51.1 写作目标.51.2 适用范围.51.3 读者范围.51.4 参考资料.51.5 名词解释.52 可读性和可维护性.72.1 命名规则.72.1.1 文件命名.72.1.2 函数命名.72.1.3 变量命名.72.1.4 数据类型命名.82.1.5 宏定义和枚举的取值.92.1.6 标准宏定义.102.2 空白的填充.102.2.1 空白行分割规则.102.2.2 空格分割规则.102.2.3 缩进规则. 112.3 注释规则. 113 文件的组织.133.1 源文件组织.133.1.1 文件头.133.1.2 头文件的包含.143.1.3 常量、宏、Typedefs 的定义.143.1.4 全局、静态变量的定义.143.1.5 静态函数类型的声明.153.1.6 函数体的排列顺序.153.2 头文件组织.153.2.1 文件头.153.2.2 防止头文件的嵌套包含.163.2.3 适应C+规则的声明方法.163.2.4 常量、宏、Typedefs 的定义.163.2.5 变量、函数的声明.164 函数的组织.174.1 函数头的格式.174.2 函数类型的定义.184.3 变量的定义.185 一般语法描述.195.1 条件判断语句.195.2 分支语句.205.3 无条件跳转语句.205.4 表达式.205.5 结构.216 附录.226.1 C 源文件示例：.226.2 H 头文件示例：.221 序言1.1 写作目标文档所包含的编码规范是在中、大规模的软件开发项目中实际使用过的。撰写这份文档的目的是为了在软件开发工作中具有相同格式的统一规范。这份规范的执行将大大提高代码的可维护性、完整性、可移植性、可读性。1.2 适用范围这份文档指明了公司内部所有软件项目的代码开发框架。文档仅仅适用于使用C 语言的软件开发工作中。在读本文档之前读者应具备相当熟练C 语言开发的工作经验，以至于读者看本文档时不需要任何额外的C 语言知识。本文档提供下列内容：􀁺 C 文件及函数的组织内容。􀁺 变量、数据类型、函数的命名规范。􀁺 结构、变量的分布、注释书写方法。􀁺 提高C 语言代码的可读性及编码效率。1.3 读者范围这份编码规范适用于所有在IPTV 软件部工作的软件设计工作者、软件开发工作者。1.4 参考资料下面列出的是一些相关的参考文档：􀁺 The C Programming Language: ANSI C Version, Brian W. Kernighan, Dennis M. Ritchie,Prentice Hall, 1988.1.5 名词解释coding standards 编码规范Naming conventions 命名规则comments 注释file organization 文件组织function organization 函数组织API Application Program Interface，应用程序接口Enum Enumerator，枚举Const int Constant Integer，整形常量CVS Concurrent Versions System (11)，一种源代码版本控制软件2 可读性和可维护性这个章节描述了增强C 源代码的可读性和可维护性的方法。内容包括：􀁺 不同类型变量、宏、数据类型、文件、函数的命名差异􀁺 空白的填充􀁺 注释书写方法2.1 命名规则文件、函数、常量、变量的命名应当采用有意义的名称定义，只有这样才能提高可读性。下面将列出一般的命名方法：􀁺 选择唯一的并且能够准确、明了的表示出变量用途的名称。􀁺 单词之间使用下划线符号连接。􀁺 避免使用容易引起歧意的名称缩写。例如：缩写“inch”有可能会被误认为“inputcharacter”，所以如果要表示“input character”，则使用in_char 的缩写会比较好些。􀁺 必须保证所使用名称的唯一性，而不要试图依赖字母大小写来区别不同的名称。􀁺 不允许变量名和typedef 使用相同的名称，这样将引起不必要的混淆。2.1.1 文件命名文件名采用MS-DOS 的8.3 短文件名格式，且所有字符均为小写。C 和H 文件的扩展名分别为*.c 和*.h。为文件命名时应尽量保证整个工程中的唯一性，应使用其所属模块名_作为前缀（模块名的长度不超过2 至4 个字符）。如：oam_alarm.cbri_extn.h2.1.2 函数命名􀁺 所有函数名称均采用大小写字符，单词间以大写字母区分。􀁺 为全局函数或API 命名时，应使用其所属模块名_作为前缀（模块名的长度不超过2至4 个字符）。如：U16 HIP_GetSlotInfo(void); /* global HIP API function */􀁺 为静态函数（如：static functions）命名时，应在该函数类型声明前使用static 关键字。如：static U8 GetNumOfBrds(void); /* static function */2.1.3 变量命名下面所列出的是不同类型变量的命名规则：􀁺 变量全部采用小写类型缩写+大小写字母命名方式，单词间以大写字母区分。如：ucLowerCase。􀁺 指针变量类型缩写前要+p，多级指针变量前+p的个数与指针级数对应；函数指针变量前要+pf。如：void * pVoid;U8 *ppcValue;􀁺 变量类型缩写如下Array aPonit pU8 ucS8 cU16 usS16 sU32 ulS32 lBOOL bstruct stunion uenum e􀁺 为全局变量命名时,应使用g_作为前缀。如：g_sLowerCase。􀁺 为静态变量命名时,应使用s_作为前缀，并以static 关键字修饰。如：static U8 * s_plLowerCase;注意：全局变量不要被外部模块之间访问，应该通过函数方式进行存取控制，所有之间访问全局变量的代码均被视为不良代码。2.1.4 数据类型命名这里主要描述typedef 和enum 两种类型的命名规则。􀁺 下面所列的是基本数据类型。如果需要另外扩充数据类型，则应在这些基本数据类型基础上进行。至于Standard C 保留的数据类型我们将不使用。如：char, int, short, longU8 unsigned 8-bitS8 signed 8-bitU16 unsigned 16-bitS16 signed 16-bitU32 unsigned 32-bitS32 signed 32-bitBOOL Boolean注意：BOOL 类型是新增的数据类型，采用typedef U32 的格式定义的。所有上面定义的数据类型都应在具体项目中的一个全局性的公共头文件中定义。􀁺 所有使用typedef 形式定义的struct 数据结构名称将使用T(或PT指针类型)作为前缀。如：typedef structU8 b; TName, *PTName;􀁺 所有使用typedef 形式定义的union 数据结构名称将使用U作为前缀。如：typedef unionU8 b;U16 a; UName;􀁺 所有使用typedef 形式定义的enum 数据结构名称将使用E作为前缀。如：typedef enumFM_INVALID_CODE,FM_INVALID_SLOT_ID, EName;􀁺 所有使用typedef 形式定义的函数指针名称将使用PF作为前缀。如：Typedef void (*PFTaskEnty)(void);2.1.5 宏定义和枚举的取值􀁺 所有宏名，const 变量名和enum 方式定义的常量名均采用大写字符，单词间以_区分􀁺 预编译宏定义前+_;􀁺 尽量避免直接使用数字常量（硬编码），取而代之的是用宏(#define)，const 和 enum 方式定义常量值。如：#define SLOT 1const U16 MAX_SLOT_NUMBER = 16enumRV_OK,RV_NO_MEM,RV_TIMEOUT,;注意：1). 避免在不同文件中使用相同的常量名。全局常量应声明在全局的公共头文件中。2). 首选使用const 类型定义替代宏定义。因为const 类型定义将有利于编译器进行类型检查。2.1.6 标准宏定义标准宏定义（如：TRUE/FALSE，SUCCESS/FAILURE 等）应该定义在全局的系统头文件中。这些宏的具体值为：#define TRUE 1#define FALSE 0#define OK 1#define NG 0#define SUCCESS 0#define FAILURE -12.2 空白的填充2.2.1 空白行分割规则空白行的使用可以增加源代码中的可读性，但过多的使用会造成源代码冗长可读性下降。一种比较好的方法是使用空白行分割源代码中的不同部分和相对独立的程序块。如：#define LOWER 0#define UPPER 300#define STEP 10/* 此处增加一行空白 */void main(void)U8 x;/* 此处增加一行空白 */* 打印字符串处理部分*/* 此处增加一行空白 */for (.;.;.)printf(); /* end of MAIN */2.2.2 空格分割规则􀁺 if，while，for 关键词后加一个空格如：while (1)􀁺 二元操作符前后加一个空格如：wCount += GAP ;􀁺 逗号后应跟一个空格如：concat(s1, s2);􀁺 (后不加空格􀁺 )、,、;前不加空格；但当;在for 循环比较语句中后应跟一个空格􀁺 一元操作符前后不加空格􀁺 _、.、->前后不加空格如：好的空格使用方法：*average = *total / *count; /* compute the average */注意：各个符号之间都有空格，如=号左右两边。不良的空格使用方法：*average=*total/*count; /* compute the average */注意：编译器会将/*作为注释的开始，而不会分别当做除号和指针标识符来对待。2.2.3 缩进规则􀁺 使用0,4 缩进格式，形式如下：if () /* 大括号另起一行 */x = y + z;􀁺 禁止使用TAB 键，缩进为4 个空格􀁺 、独占一行，成对对其不缩进2.3 注释规则在源代码中添加注释将能使阅读者轻松阅读并提高效率。从用途来分，注释级别分为：􀁺 文件级：说明当前整个文件的用途等信息。一般放在当前文件的开始处。􀁺 函数级：说明当前函数的功能、输入/输出参数、返回值等信息。一般放在当前函数的开始处。􀁺 代码级：说明当前行的代码意义、注意事项等信息。一般紧跟注释所说明的代码后面，且与上下文有空行分割以便阅读。从风格来分，注释级别分为：􀁺 盒型(Boxed comments）：说明大略意图。一般用于说明整个文件或函数的用途等信息。􀁺 块型(Block comments)：对大快的代码进行注释，一般是采用/*和*/成对联用的形式。如：/* Write comment text there, in complete sentences.* Use block comments when there is more than one sentence or* more than one line.*/􀁺 行型(Inline comments)：与被注释代码在同一行且一般放置在代码之后。可用来说明代码、变量等的意义。如：U8 slot_id; /* slot Id is */X = y + z; /* x is , y is , z is */􀁺 简型(Short comments)：采用与被注释源代码相同缩进格式的方式。值得注意的是，C+的双斜杠注释方法/在C 源代码中是不应该使用的。这主要是考虑到避免有的编译器仅支持标准C 而不支持C+时会出现的编译错误。如：switch (type)/* Perform case for card types */case PRI_CARD:case FXS_CARD:default:break;3 文件的组织在这个章节中我们主要讨论关于如何组织C 源文件和H 文件。3.1 源文件组织下图提供了源文件的组织概况。文件头File Header需包含头的文件Header File IncludesDefines and Typedefs that apply to the file as a whole, including:常量定义Constant macro defines宏函数定义parameterized macro defines枚举定义EnumsTypedefsGlobal data definitionLocal data definitionLocal function declarationFunctionsfunction headerfunction body3.1.1 文件头下面是IPTV 软件部定义的标准文件头/*Copyright (c) 2006, Shenzhen HiMedia Technology Co.,Ltd* All Rights Reserved.* Subsystem ：IPTV/PBXXXX* File : xyz.c* Created By : ZZZZ* Purpose:* This file contains the implementation of xyz feature.* History:* Programmer Date Ver Description* - - - -* Kexiong 01/16/05 00.00 Demo.*/3.1.2 头文件的包含要确定源代码中的头文件信息就必须用#include 预编译指令。为了达到简洁、清晰的效果，应该保证仅仅包含必要的头文件，如果所包含的头文件已经不再需要则应该将该#include语句注释或删除。􀁺 头文件被包含顺序应为（请注意include 后面所跟的括号类型）：#include <system header files>#include “toollibraries header files”#include “subsystem header files”#include “module header files”注意：一对尖括号<>仅仅用于包含标准C 系统的头文件时才使用，一对引号”是用来包含除标准C 以外的所有头文件。3.1.3 常量、宏、Typedefs 的定义常量、宏、Typedefs 的定义位置是放在所有被包含的头文件位置之后的。不同种类的定义其先后排列顺序为：􀁺 宏常量(#define identifier token-string)􀁺 宏函数(#define identifier(identifier, , identifier) token-string)􀁺 枚举Enums􀁺 Typedefs注意：这些定义的有效性仅仅存在于当前所在的文件范围之内，如果需要在其他文件中也有效，则需要将该定义放入共同包含的头文件中。3.1.4 全局、静态变量的定义在常量、宏、Typedefs 的定义之后，将开始定义全局和静态变量。其位置顺序如下：􀁺 全局变量(global variable)。􀁺 静态变量(local variable)。如：U8 g_ucTrapId = 0; /* global variable */static U16 s_sSave; /* local variable */3.1.5 静态函数类型的声明静态局部函数的类型声明将放在静态变量定义之后。局部函数的有效范围为当前所处文件。函数类型声明的最左边应使用static 关键字。函数参数的变量也应同时被包含在该函数类型的声明中。如：static U16 GetSlotId(U8 ucBoardType);3.1.6 函数体的排列顺序在源文件中，推荐函数定义顺序如下：􀁺 如果文件包含main 函数，则该main 函数将被放在其他所有函数体之前。􀁺 将所有逻辑上相关的函数放在同一文件中。􀁺 如果是普通意义的功能性函数，按字母顺序排列每个函数的位置。关于函数的组织（函数头和函数体）将在下一章节介绍。3.2 头文件组织下图提供了头文件的组织概况。文件头File Header防止被嵌套包含的宏定义Opening nested inclusion directive需包含头的头文件Header File Includes.Defines and Typedefs that are shared by multiple files, including:常量定义constant macro defines宏函数定义Parameterized macro defines枚举定义EnumsTypedefsExternal data declarationsExternal function declarationsClosing nested inclusion directive3.2.1 文件头与源文件规则相同。3.2.2 防止头文件的嵌套包含防止头文件被嵌套包含的方法是由在该头文件中定义相关的宏定义来实现的。格式如下#ifndef _HEADERNAME_H_#define _HEADERNAME_H_#endif3.2.3 适应C+规则的声明方法考虑到被C+文件所包含的C 头文件也将按照C+方式编译，所以C 头文件中应该对函数类型声明作以下处理：#ifdef _cplusplusextern “c” #endifC 函数类型声明列表#ifdef _cplusplus#endif3.2.4 常量、宏、Typedefs 的定义与源文件规则相同。3.2.5 变量、函数的声明在头文件中是不应该定义变量实体和函数实体的，因为这将在多个源文件同时包含该头文件的情况下引起重复定义错误。因此在头文件中仅仅存放变量、函数的声明，以便于别的源文件可以调用即可。4 函数的组织在这个章节中我们主要讨论关于如何组织函数体。一个比较小的函数体是容易被阅读者所理解的。一般而言一个函数体除了注释以外是不超过100 行代码的长度的。函数类型名词解释：􀁺 微型函数：<7 行代码。这种代码是可以允许自由书写格式的。􀁺 一般函数：>=7 行代码。大约90%的函数都属于这种类型，也是我们将讨论的函数类型。下图提供了函数的组织概况。函数头Function header函数类型声明Function declaration变量声明Variable declaration内部静态变量定义static internal variable局部变量定义automatic variableStatements within the function4.1 函数头的格式/* Description:* send TRAP notification to the Network Manager.* Argument Type IO Description* - - - -* trap_id U8 I TRAP Identifier* trap_value S16 I TRAP General Entity (or value)* Return Value: rv_t SUCCESS/FAILURE value* SUCCESS* FAILURE* History (Recommended but Optional):* Programmer Date Description of Revision* - - -* John Q. Public m