C语言编程风格规范.doc

C Coding Style and StandardsC语言编程风格与规范GemwayC语言编程风格与规范C Coding Style and Standards 1 概述11.1 目的与适用范围11.2 程序文档(Coding Document)11.3 编程风格(Coding Style)12 注释规则(Commenting Conventions)22.1 注释的原则22.2 注释的写法23 命名规则(Naming Conventions)73.1 命名的原则73.2 函数的命名83.3 宏、常量、标识符和标号的命名83.4 类型的命名93.5 变量的命名94 文件体制(Files Organization)134.1 文件命名规则（File Naming Conventions）134.2 目录体制(Directory Organization)144.3 源代码文件（Program Files）144.3.1 文件结构144.3.2 一般规范154.3.3 表达式书写164.3.4 语句格式174.3.5 断言设置184.3.6 变量初值194.3.7 变量置空194.3.8 人为制造错误194.3.9 统一的函数出口204.3.10 错误处理214.3.11 范例224.4 头文件(Header File)254.4.1 头文件结构254.4.2 范例254.5 工程文件(MAKEFILE)284.6 其它文件（Other Files）31概述目的与适用范围本文件旨在统一本公司的C语言编程风格(C Coding Style)，制定一系列编程规范(Coding Standards)，使得各项目小组能使用简单、一致、美观的风格进行代码和程序文档的编写，清楚、准确地表达程序员的意图，方便阅读，减少错误，使得程序容易理解、修改、测试和使用。本文件将达到以下目的：增强程序易理解性提高软件可靠性提高软件可维护性提高软件开发效率本文件以MicroSoft Windows 3.1 Application的程序为范例进行规则描述，其规则适用于其它各种系统下的C语言程序。本文件的使用对象是有经验的程序员，常识性的概念和术语不另外解释。程序文档(Coding Document)程序文档描述程序数据及过程的组成部分、程序做些什么、程序为什么这样做。程序文档被用来了解一个程序内部结构，了解一个软件系统内的程序与程序之间、程序与操作系统之间、程序与其它软件系统之间的相互作用。程序文档对软件的开发和维护是必不可少的，是一个好的编程风格的重要部分。好的文档应该是简单明了、容易更新、风格一致，同时充分使用编程语言的表达能力，使程序成为自身的文档。程序就是文档(Program is Document)！如果一个程序结构良好，注释完善，程序源代码就可以提供全部必要的程序文档。将程序文档建于代码之中，会使程序的复查和修改、程序文档的更新更为容易。编程风格(Coding Style)好的编程风格简单、一致、美观，编写的程序结构良好、层次分明、思路清晰，其规则不会复杂得使读者为弄清书写格式而伤脑筋。程序员在编程过程中必须经常考虑到“怎样更好地测试我的程序？”，使得自己的程序结构清晰整齐，易于测试和排错。本规范要求采用下述编程风格和编档技术：程序文档建立在源代码中有选择性的高级注释采用意义明确的名字用缩进格式编写编程风格前后一致结构化程序设计统一函数出口运用这些技术可以减少对程序注释的需要，并有助于程序自编文档，此外还可以改善程序文档的可维护性。注释规则(Commenting Conventions)注释的原则注释的目的是使读者在思想上形成一个概念，从而正确地理解程序。一般来说，说明程序功能并描述程序各组成部分相互关系的高级注释是最有用的，而逐行解释程序指令如何工作的低级注释则不利于读、写和修改，是不必要的，也是难以维护的。本规范反对使程序代码由于大量冗长的注释而凌乱不堪，注释与代码的行数比在0.8：1时比较合适。程序员在写注释时，不是逐行地去弄懂某个程序，而是将指令归并，形成更高一级且更易理解的组合：块(Block)（如：用以实现“在报表上画出标题”这段程序）。在源代码中，注释应放在每一块之前，以说明该程序块的作用。程序块的具体操作不用在注释中描述，由程序中有意义的命名来反应，可以通过阅读代码来了解。指令注释应该尽量少用。不需要对每条程序指令、每一控制过程、每个决策点都作出注释。指令注释只用于特殊情况，如说明某个少见的、复杂的或者经过优化的算法，指出关键的操作、容易出错的程序段以及有可能混淆之处。对于主要的数据结构、变量，则应不厌其烦地予以注释。注释的写法函数描述在每个函数之间必须有一段函数描述，描述的每个部分由标识字开头，意义分别如下：doc函数类型（CALLBACK、EVENT HANDLER、PUBLIC、INTERNAL）api函数名及函数功能说明parm参数及其描述(在参数描述中说明参数联结的数据，如指针所指向的内存等。说明取值范围。用于输入、输出、输入/输出的参数分别用关键字Iparm、Oparm、IOparm表示)static静态变量及其描述(对静态变量的使用和修改。用于输入、输出、输入/输出的静态变量分别用关键字Istatic、Ostatic、IOstatic表示)global全局变量及其描述(对全局变量的使用和修改。用于输入、输出、输入/输出的全局变量分别用关键字Iglobal、Oglobal、IOglobal表示)rdesc返回值格式如下：/*doc 函数类型api 返回值类型 | 函数名 | 函数功能说明.parm 参数类型n | 参数n | 参数描述n.static 静态变量类型n | 静态变量n | 静态变量描述n.global 全局变量类型n | 全局变量n | 全局变量描述n.rdesc 返回值描述.*/块注释程序块是指“完成某个功能的指令的集合”，程序块小结了代码，把代码分成小的可理解的单元。程序块的注释应该是简短并且经过标号的，用于描述程序块的处理步骤。块注释在要注释的程序块之前，每一注释行用“ *”开头，每一注释块开始和结尾各有一个分别以“/*”和“*/”开头的空行。在注释块前有一行空行与其他程序代码分隔。块注释不同步骤之间用“STEPn”标号，写法如下：.（其它程序代码)/* * STEP1: * 程序块注释第一行 * 程序块注释第二行 * STEP2: * . */(需要注释的程序块).行注释行注释在要注释的若干重要指令之前，用以说明某个少见的、复杂的或者经过优化的算法，指出关键的操作、容易出错的程序段以及有可能混淆之处。每一注释行用“/*/”对包括。注释前有一行空行与其他指令分隔。写法如下：.(其他程序代码)/* 行注释第一行 */* 行注释第二行 */* . */(需要注释的指令).嵌套的注释当程序用“”组成复合语句，并且嵌套超过一层时，应在“”和“”的右边说明复合语句的开始和结束，以利于分辨嵌套层次。注释用“/*/”对包括，如果注释太长需换行时，下一行仍以“/*/”对包括。if (.) /* Begin of if */ . /* End of if */else /* Begin of else */ . /* End of else */.while (.) /* Begin of while */ . /* End of while */.do /* Begin of do */ . while (.) /* End of do */cfor (.) /* Begin of for */ . /* End of for */.switch /* Begin of switch */ . /* End of switch */省略的注释C中有几处小的省略可能影响程序动作，应在省略的地方加上注释，说明是故意省略的。如在循环控制中略去参数、略去循环体、在switch语句中略去breaak等。其格式举例如下：for (/*current value of i*/; i=0.0)?(x):-(x)类型变量说明存在于变量中的数据的用途，解释数据重要的全部理由。试着指出不仅仅是什么数据存在变量中，还要指出为什么该数据存在该变量中。例如：char strInputBufBUF_SIZE; /* source for line */ /* scanning */short sBufferedBytes;/* count of achInputBuf contents: */ /* -tracks unprocessed data */ /* -force buffer refill when 0 */参数对函数的参数除了象变量一样进行注释外，还要指出一个参数是否是：输入参数、输出参数、输入输出参数。这些注释用“/*/”对包括，可以在需注释部分的前面或右边，如果注释太长需换行时，下一行仍以“/*/”对包括。NOTE: 对外部变量和外部函数进行注释时，应同时说明外部变量和外部函数所在的文件名。例：一些常用的注释：#include .; /* 包含语句注释 */#define .; /* 定义语句注释 */typedef .; /* 类型定义语句注释 */extern .; /* 外部说明注释 */struct .; /* 结构说明注释 */static .; /* 静态数据注释 */typename .; /* 变量注释 */命名规则(Naming Conventions)命名的原则理解程序中每个函数名、常量、标识符、标号、类型、变量的含义是理解程序的关键。命名的选择应该直观、易于理解，使读者可以通过名字了解函数的功能、变量的用途等等。命名时应符合以下原则：采用有实际意义的名称例如，用dDistance = nTime*nSpeed要比dD = nT*nS更容易理解。不用过于相似的命名例如，nELL、nENN、nEMMM这样的变量命名容易混淆，又如pszTheFirstBoox和pszTheFirstBook仅在末尾有不相同的字母，不安全。应在前8个字符中有所区分。命名不应仅由大小写区分，如xPushButtonWid和xPushbuttonWid是错误的命名。名称中一般不要带数字由于数字0、1、2、5易于同字母O、I、Z、S混淆，因此象变量名称nXOSS难以被人区分。同一命名不要有多种含义命名时要加注释函数的命名函数名用有实际意义的单词或缩写字母组成。每个单词的第一个字母大写，其它字母小写，缩写字母一律大写。单词或缩写字母之间直接连接。例如：DrawChart()，DeleteFCB()。为明显区别，对于Call Back函数(在X Window、MS Windows中)，末尾加上CB，如：PushButtonCB()；对于Event Handler函数(在X Window中)，末尾加上EH，如：CanvansEventEH()。宏、常量、标识符和标号的命名命名宏、常量、标识符和标号名一律大写，用有实际意义的单词或缩写字母组成，单词或缩写字母之间用下划线“_”连接或没有分隔。宏统一加后缀“_MAC”。标号统一加后缀“_EXIT”。如：PROFILENAME，MAX_FLOAT_LEN，FAILURE_EXIT。前缀同一类常量及标识符，应使用前缀予以区分。如最大值前缀：MAX_，最小值前缀：MIN_，长度前缀：LEN_，等等。标识常量（ID）的前缀：资源ID：IDR_如：IDR_FACEBITMAP对话框ID：IDD_如：IDD_ABOUT菜单ID：IDM_如：IDM_FILEOPEN字符串ID：IDS_如：IDS_CANTOPEN枚举类型的后缀为了区分不同枚举类型的成员，每个枚举类型的成员应该以该枚举类型名字的缩写作为后缀，例如：typedef enum tagDOTTYPE NORMAL_DT, CENTROID_DT, MARK_DT DOTTYPE;用枚举类型代替固定意义的一组常量对于具有固定意义的一组常量，应该用枚举类型来代替。例如，应该用：typedef enum tagDOTTYPE NORMAL_DT, CENTROID_DT, MARK_DT DOTTYPE;来代替：define NORMAL0define CENTROID1define MARK2以表示点的不同类型。类型的命名命名类型名一律大写，用有实际意义的单词或缩写字母组成，单词或缩写字母之间没有分隔。C+的类名一律加前缀大写字母C，后续部分用有实际意义的单词或缩写字母组成，应能简要指示变量的含义。每个单词的第一个字母大写，其它字母小写，缩写字母一律大写。单词或缩写字母之间直接连接。例如：class CWinApp : public CCmdTarget .类型的定义方式见以下例子说明。指针如果在程序中要以指针方式引用该类型，则应同时定义该类型的各种指针类型，程序中不直接使用“*”的方式定义指针。这样有利于程序的修改和维护。指针类型的命名方法是：缺省指针（依赖于编译模式）P+类型名近指针NP+类型名远指针LP+类型名巨指针HP+类型名常量指针(P、NP、LP、或HP)+C+类型名例：SHEETDATA及其指针类型的定义：typedef struct tagSHEETDATAintnSheetName;. SHEETDATA;typedef SHEETDATA *PSHEETDATA;typedef SHEETDATA NEAR *NPSHEETDATA;typedef SHEETDATA FAR *LPSHEETDATA;typedef SHEETDATA HUGE *HPSHEETDATA;typedef const SHEETDATA FAR *LPCSHEETDATA;变量的命名命名变量名按以下规则命名：变量名：前缀+变量意义描述其中前缀用以代表变量的数据类型的；变量意义描述用有实际意义的单词或缩写字母组成，应能简要指示变量的含义。每个单词的第一个字母大写，其它字母小写，缩写字母一律大写。单词或缩写字母之间直接连接。循环变量如i、j、k例外，可以仅由一个字母组成。对于X Window程序，变量“arg, n, string”以及Call back, event handler函数的参数“w, clinet_data, call_data, event”，可以按X Window的惯例命名。例：nNumberOfFCB，szFileName前缀变量的前缀代表不同的数据类型。对于X Windows(包括Xlib、X Intrinsics、Motif、Open Window等等)类型的变量，前缀用x，后缀用相应类型的前四个字符。例如：WidgetxCanvasWidg;WindowxControlWind;EventxPushEven;ArgListxArgsArgL;StringxCanvasStri;如果后缀前四个字符不能区分两个类型，则第四个字符取类型命名的下一个大写字母，例如：WidgetxCanvasWidg;WidgetListxCanvasWidL;WidgetClassxPanelWidC;如果X Windows变量在结构中出现，并且结构类型名已经指出该变量类型，则不用后缀，例如以下结构中，每个成员都是Widget类型：typedef struct tagSYSTEMWIDGETS WidgetxCanvas; . SYSTEMWIDGETS;对于全局变量，另外在其它前缀之前加一个字母“g”表明它是全局变量。例如：WORDgwMessage;表示gwMessage是WORD类型的全局变量。对于C+类的成员，变量名除按C的命名规则进行定义以外，前面再加上前缀m_，表示这是一个类的成员。例如class CWinApp : public CCmdTarget HINSTANCEm_hInstance; HINSTANCEm_hPrevInstance; LPSTRm_lpCmdLine; intm_nCmdShow; .各种数据类型相应的前缀如下：类型前缀举例charchcharchInput;shortsshortsWidth;intnintnNumber;longllonglValue;floatffloatfRate;doubledodoubledoTotal;unsignedununsignedunLength;BYTEbyBYTEbyMask;WORDwWORDwMessage;DWORDdwDWORDdwDistance;BOOLbBOOLbFinished;HANDLEhHANDLEhMemBlockH.hHBITMAPhBitmapaBYTEabyMasks10;char szcharszFileName64;structstPOINTstPoint;unionuCELLuValueOfCell;enumeIOMODEeChartIOMode;staticsstatic charschMulti;constcconst charcchVersion;P.pPBYTEpbyMask;PC.pcPCBYTEpcbyMask;P(结构）pstPPOINTpstPoint;PSTRpszPSTRpszName;NP.npNPBYTEnpbyMask;NPC.npcNPCBYTEnpcbyMask;NP(结构）npstNPPOINTnpstPoint;NPSTRnpszNPSTRnpszName;LP.lpLPBYTElpbyMaskLPC.lpcLPCBYTElpcbyMask;LP(结构）lpstLPPOINTlpstPoint;LPSTRlpszLPSTRlpszName;HP.hpHPBYTEhpbyMask;HPC.hpcHPCBYTEhpcbyMask;HP(结构）hpstHPPOINThpstPoint;HPSTRhpszHPSTRhpszName;X Window类型xWidgetxCanvasWidg;C+对象oCViewoView;文件体制(Files Organization)程序文件指完成一个可运行程序所需要的所有相关代码文件及描述文件。例如在一个MicroSoft Windows 3.1 Application的开发中，一般需要以下程序文件：工程文件(MAKEFILE)，头文件（.H），源代码文件（.C），动态连接库文件（.DLL），可执行代码文件（.EXE），资源文件（.RC），对话框文件（.DLG），图符文件（.ICO），位图文件（.BMP），模块定义（.DEF），帮助工程文件（.HPJ），帮助文本文件（.RTF)，帮助文件（.HLP)，自述文件（README)。文件命名规则（File Naming Conventions）程序文件的文件名按以下规则命名：文件名：项目（子项目）名缩写+文件内容描述+.+文件后缀如dbqchart.c，表明该文件属于子项目dbq(Data Base Query)，内容是有关chart的操作，是一个C源代码文件(.C)。项目或子项目名的缩写由项目组长认可，在项目组内统一使用。不同的后缀表示不同类型的文件，定义如下：C头文件（.H）C+头文件（.HPP）MASM头文件（.INC）C源代码文件（.C）C+源代码文件（.CPP）MASM源代码文件（.ASM）目标代码文件（.OBJ/.O）动态连接库文件（.DLL）库文件（.LIB）可执行代码文件（.EXE或.COM）资源文件（.RC）对话框文件（.DLG）图符文件（.ICO）位图文件（.BMP）模块定义（.DEF）帮助工程文件（.HPJ）帮助文本文件（.RTF)帮助文件（.HLP)图2：程序文件后缀(Coding Files Suffix)另外，用“MAKEFILE”表示工程控制文件，用“README”表示本项目的内容摘要文件。目录体制(Directory Organization)在一个项目(Project)的开发过程中，项目组长负责建立该项目的项目目录(Project Directory)，以组织存放与该项目有关的程序文件。项目目录的一般结构如下：NOTE 子项目是项目中具有单独的可执行代码的相对独立的子系统，其特征是每个子项目都具有自己的MAKEFILE，一个项目中包含几个MAKEFILE就有几个子项目。如果项目中只有一个MAKEFILE，则不需要SUBPROJECTn子项目目录，直接在PROJECT.SRC目录下建立CODE、INCLUDE、DOC目录即可。如果CODE目录下的源代码(.C)文件比较多，可以建立若干子目录分类管理。在CODE及INCLUDE目录下的文件中对自定义的.H文件的引用应写为路径名形式：“.include文件名.h”或“.include文件名.h”（如果CODE下还有子目录）。项目目录的实际形式最终由项目组长根据不同项目的具体情况决定。源代码文件（Program Files）文件结构一个源代码文件按照顺序应该包括以下内容：序(Prologue)包括文件名、版权信息、项目名、日期、函数清单（列出本文件中所有的函数名和作者）、备注。头文件的包含语句(Header File Include)定义(Defines and Typedefs)局部使用的常量定义局部使用的类型定义全局变量说明(Global Data Declarations)非静态全局变量说明静态全局变量说明函数(Functions)包括所有函数。一般规范格式程序文件最长应该在1000行左右，每行的长度不应该超过80个字符。每行只能有一条语句。句行长度超过80个字符时应分成多行书写，附加行都向右缩进一层。程序中的C语句一律用小写字母（注释除外），并按层次书写。不同层次的语句向右缩进4个字符（一般用制表键TAB）。使用花括号组成块时，花括号内的语句向右缩进，花括号本身与其外层语句对齐。在程序中，除字符串外，其余在任何地方遇“;”均换行。换行后，除按格式要求应缩格外，其余均与前一行的左端对齐。不要象律师写合同那样写代码，应该使用简单的语言，让所有的程序员都能阅读和理解。类型当有自定义的类型时，变量声明时应优先使用自定义的类型。除了使用位串或值域的要求之外，宁可使用signed，也不使用unsigned类型。仅对字符数据使用char类型，否则用BYTE(usigned char)类型。如果要求表示的值不超过16位，应使用int类型，否则使用long类型，以保证系统的可移植性。不要使用short类型。用double代替float。除非空间很重要，否则浮点函数和变量都应被声明为double。尽量避免不同的指针类型之间、指针与其它类型之间的转换，不可避免时必须用显式的操作符标记。不得使用隐含类型，必须显式定义每个函数的参数和返回值的类型，没有返回值的函数定义为void。其它在语句中不得使用数字，必须使用常量、NULL、TRUE、FALSE等。当循环体至少执行一次时，使用do-while循环，否则使用while或for