程序员编码规范

1、程序员编码规范目 录1.导言1.1目的1.2范围1.3缩写说明1.4术语定义1.5引用标准1.6参考资料1.7版本更新信息2. 编码格式规范3.命名规范3. 1命名的基本约定3. 2各种标示符类型的命名约定3. 3组件名称缩写列表4声明规范4.1变量声明4.2代码缩进4.3空白5语句规范6.注释规范6. 1注释的方法6. 2开头注释6. 3类和接口的注释1. 导言1.1目的该文档的目的是描述网上招聘系统项目的编码规范和对代码的说明，其主要内容包括：l 编码规范l 命名规范l 注释规范l 语句规范l 声明规范l 目录设置l 代码说明本文档的预期的读者是：l 开发人员l 项目管理人员l 质量保证人

2、员1.2范围该文档定义了本项目的代码编写规范，以及部分代码描述和所有代码的说明。1.3缩写说明AspxAspx是Active Server Pages XML的缩写。1.4术语定义ClassC#程序的单元。Packages 由很多的类组成的工作包。 1.5引用标准1 企业文档格式标准 北京长江软件有限公司 1.6参考资料书名：系统分析设计技术 作者：张友生C#程序设计2. 编码格式规范1代码书写格式（1）所有的缩进TAB键为4个空格，每个单词的首字符大写，其余小写。（2）在代码中垂直对齐左括号和右括号。例： if(x=0) Response.Write("用户名必须输入！"

3、); 不允许以下情况： if(x=0) Response.Write("用户名必须输入！");或者 if(x=0)Response.Write("用户名必须输入！");（3）在大多数运算符之前和之后使用空格，这样做时不会改变代码的的意图却可以使代码容易阅读。例：int j = i + k;而不应写为：int j=i+k;（4）缩写SQL语句时，对于关键字使用全部大写，对于数据库元素（如表，列和视图）使用大小写混合）。（5）将每个主要的SQL子句放在不同的行上，这样更容易阅读和编辑语句。2.注释的写法（1）在你劳神的地方请加上详细的注释说明，除了最简单的存

4、取成员变量的Set/Get成员函数之外，其余大部分的函数写上注释是良好的习惯，尽量使你的程序让别人很容易看懂。（2）大多的注释会使很难看，但一些复杂的算法和数据结构和数据结构处还是要加上注释的，这样别人就容易看懂，否则时间长了，你自己都未必卸载明白了。（3）如果是对某一段程序（算法/结构）的注释，在程序头直接用/再空一格进行说明，一行不要超过80个字符。（4）为了防止在阅读代码时不得不左右流动源代码编辑器，每行代码或注释在不得超过一显示屏。（5）使用连续的多个/表示注释行（不要超过80字符）。（6）文件头部应有注释，简单描述文件的内容（7）对于程序中的比较关键的算法和函数，必须加注释。3cs文

5、件的书写（1）各个部分应使用注释行和空行分割，并在必要的地方写上注释。（2）函数之间用注释各空行分割。中间的内容缩进一个TAB三.其他1.变量(1)float和bool禁止用"="判断.bool应该用逻辑运算关系符,而float应该用差值区间来判断"相等"(2)类型转换一律用显示类型转换(3)类型的长度一律用sizeof()获得;(4)当声明一个变量时,务必要自已初始化一下变量;2.函数(1)功能单一,函数名要名符其实.(2)要易懂,实现时要根过分追求技巧,优化放到后面去做.(3)长度一般禁止超过200行.(4)要检查输入值是否合法,实现(成员)函数时务

6、必要求输入参数是在要求范围之内,尤其你定义的(成员)函数给别人调用时,要判断其合法性.(5)调用函数时要严格按照接口规范调用,调用后要判断执行情况,并做适当的错误处理(尔后会给出错误和异常处理规范)(6)尽量避免整块复制代码段,如果出现这样的情况要分析原因,如果这段代码完成独立的功能,应考虑使用函数,否则,应考虑使用宏定义,否则因为修改引起的不一致往往是错误的根源.(7)除极其简单的函数外,其他的函数在稿处必须加上FMAT_TARCE(),参见错误异常处理规范.(8)函数的出口尽量唯一,最好在出口处加上FMAT_TRCE();(9)写代码时,尽量减少堆的分配次数,能使用Stack的尽量使用St

7、ack(10)函数编写必须精练,消除冗余的代码,删除不用的变量(11)if/while等语句中和条件表达式的运算结果必须为显示的Bool量(12)禁止使用goto语句附:标识符 大小写方式 示例 标识符大小写规则 标识符 大小写 示例 类 Pascal AppDomain 枚举类型 Pascal ErrorLevel 枚举值 Pascal FataError 事件 Pascal ValueChanged 异常类 Pascal WebException 只读的静态字段 Pascal ReadValue 接口 Pascal IDisposable 方法 Pascal ToString 命名空间 P

8、ascal System.Drawing 属性 Pascal BackColor 参数 Camel typeName3.命名规范 3.1命名的基本约定1> 要使用可以准确说明变量/字段/类的完整的英文描述符，如firstName。对一些作用显而易见的变量可以采用简单的命名，如在循环里的递增（减）变量就可以 被命名为 “i”。2> 要尽量采用项目所涉及领域的术语。3> 要采用大小写混合，提高名字的可读性。为区分一个标识符中的多个单词，把标识符中的每个单词的首字母大写。不采用下划线作分隔字符的写法。有两种适合的书写方法，适应于不同类型的标识符：PasalCasing：标识符的第一

9、个单词的字母大写；camelCasing：标识符的第一个单词的字母小写。4> 下表描述了不同类型标识符的大小写规则：标识符大小写示例命名空间Pascalnamespace Com.Techstar.ProductionCenter类型Pascalpublic class DevsList接口Pascalpublic interface ITableModel方法Pascalpublic void UpdateData()属性PascalPublic int Length事件Pascalpublic event EventHandler Changed;私有字段Camelprivate s

10、tring fieldName;非私有字段Pascalpublic string FieldName；枚举值PascalFileModeAppend参数Camelpublic void UpdateData(string fieldName)局部变量Camelstring fieldName;5> 避免使用缩写，如果一定要使用，就谨慎使用。同时，应该保留一个标准缩写的列表，并且在使用时保持一致。6> 对常见缩略词，两个字母的缩写要采用统一大小写的方式（示例：ioStream， getIOStream）；多字母缩写采用首字母大写，其他字母小写的方式（示例： getHtmlTag）；7

11、> 避免使用长名字（最好不超过 15 个字母）。8> 避免使用相似或者仅在大小写上有区别的名字。3.2 各种标示符类型的命名约定1> 程序集命名实验室名称（Lab）+ 项目名称 + 模块名称（可选），例如：中心服务器程序集：Lab.SeverCenter；中心服务器业务逻辑程序集：Lab.SeverCenter.Business；2> 命名空间命名采用和程序集命名相同的方式：实验室名称（Lab）+ 项目名称 + 模块名称。 另外，一般情况下建议命名空间和目录结构相同。例如：中心服务器：Lab.SeverCenter；中心服务器下的用户控件：Lab.SeverCenter

12、.UserControl；中心服务器业务逻辑：Lab.SeverCenter.Business；中心服务器数据访问：Lab.SeverCenter.Data；3> 程序集和DLLl 大多数情况下，程序集包含全部或部分可重用库，且它包含在单个动态链接库(DLL) 中。l 一个程序集可拆分到多个DLL 中，但这非常少见，在此准则中也没有说明。l 程序集和DLL 是库的物理组织，而命名空间是逻辑组织，其构成应与程序集的组织无关。l 命名空间可以且经常跨越多个程序集。可以考虑如下模式命名DLL： <Company>.<Component>.dll 例：Lab.SeverC

13、enter.dll4> 类和接口命名l 类的名字要用名词；l 避免使用单词的缩写，除非它的缩写已经广为人知，如HTTP。l 接口的名字要以字母I开头。保证对接口的标准实现名字只相差一个“I”前缀，例如对IComponent接口的标准实现为Component；l 泛型类型参数的命名：命名要为T或者以T开头的描述性名字，例如：public class List<T>public class MyClass<Tsession>l 对同一项目的不同命名空间中的类，命名避免重复。避免引用时的冲突和混淆；5> 方法命名l 第一个单词一般是动词；l 如果方法返回一个成员变

14、量的值，方法名一般为Get+成员变量名，如若返回的值 是bool变量，一般以Is作为前缀。另外，如果必要，考虑用属性来替代方法；l 如果方法修改一个成员变量的值，方法名一般为：Set + 成员变量名。同上，考虑 用属性来替代方法。6> 变量命名l 按照使用范围来分，我们代码中的变量的基本上有以下几种类型，类的公有变量；类的私有变量（受保护同公有）；方法的参数变量；方法内部使用的局部变量。这些变量的命名规则基本相同，见标识符大小写对照表。区别如下：a) 类的公有变量按通常的方式命名，无特殊要求；b) 类的私有变量采用两种方式均可：采用加“m”前缀，例如mWorkerName;c) 方法的参

15、数变量采用camalString，例如workerName；l 方法内部的局部变量采用camalString，例如workerName。l 不要用_或&作为第一个字母；l 尽量要使用短而且具有意义的单词；l 单字符的变量名一般只用于生命期非常短暂的变量：i,j,k,m,n一般用于integer；c,d,e 一般用于characters；s用于stringl 如果变量是集合，则变量名要用复数。例如表格的行数，命名应为：RowsCount；l 命名组件要采用匈牙利命名法，所有前缀均应遵循同一个组件名称缩写列表3.3 组件名称缩写列表缩写的基本原则是取组件类名各单词的第一个字母，如果只有一个

16、单词，则去掉其中的元音，留下辅音。缩写全部为小写。组件类型缩写例子LabelLbllblNoteTextBoxTxttxtNameButtonBtnbtnOKImageButtonIbibOKLinkButtonLblbJumpHyperLinkHlhlJumpDropDownListDdlddlListCheckBoxCbcbChoiceCheckBoxListCblcblGroupRadioButtonRbrbChoiceRadioButtonListRblrblGroupImageImgimgBeautyPanelPnlpnlTreeTreeViewTvtvUnitWebComTable

17、WctwctBasicImageDateTimeInputDtidtiStartComboBoxCbcbListMyImageButtonMibmibOKWebComm.TreeViewTvtvUnitPageBarPbpbMaster4.声明规范4.1 变量声明：为了保持更好的阅读习惯，请不要把多个变量声明写在一行中，即一行只声明一个变量。例如：String strTest1, strTest2;应写成：String strTest1;String strTest2;4.2代码缩进：l 一致的代码缩进风格，有利于代码的结构层次的表达，使代码更容易阅读和传阅；l 代码缩进使用Tab键实现，最好

18、不要使用空格，为保证在不同机器上使代码缩进保持一致，特此规定C#的Tab键宽度为4个字符，设定界面如下(工具选项)：l 避免方法中有超过5个参数的情况，一般以2,3个为宜。如果超过了，则应使用struct来传递多个参数。l 为了更容易阅读，代码行请不要太长，最好的宽度是屏幕宽度（根据不同的显示分辩率其可见宽度也不同）。请不要超过您正在使用的屏幕宽度。（每行代码不要超过80个字符。）l 程序中不应使用goto语句。l 在switch语句中总是要default子句来显示信息。l 方法参数多于8个时采用结构体或类方式传递l 操作符/运算符左右空一个半角空格l 所有块的号分别放置一行，并嵌套对齐，不要

19、放在同一行上 4.3空白：l 空行将逻辑相关的代码段分隔开，以提高可读性。l 下列情况应该总是使用两个空行：a) 一个源文件的两个片段(section)之间。b) 类声明和接口声明之间。l 下列情况应该总是使用一个空行：a) 两个方法之间。b) 方法内的局部变量和方法的第一条语句之间。c) 块注释（参见"5.1.1"）或单行注释（参见"5.1.2"）之前。d) 一个方法内的两个逻辑段之间，用以提高可读性。l 下列情况应该总是使用空格：a) 空白应该位于参数列表中逗号的后面，如：void UpdateData(int a, int b)b) 所有的二元运算

20、符，除了"."，应该使用空格将之与操作数分开。一元操作符和操作数之间不因该加空格，比如：负号("-")、自增("+")和自减("-")。例 如：a += c + d;d+;c) for 语句中的表达式应该被空格分开，例如：for (expr1; expr2; expr3)d) 强制转型后应该跟一个空格，例如：char c;int a = 1;c = (char) a;5.语句规范5.1l 【规则5-1-1】在每个函数、结构体、枚举定义结束之后都要加空行。l 【规则5-1-2】在一个函数体内，逻辑密切相关的语句之间不

21、加空行，其它地方应加空行分隔。struct st1 ;/ 空行enum ;/ 空行void Function1() / 空行void Function2() / 空行while (condition)statement1;/ 空行if (condition) statement2;elsestatement3;/ 空行statement4; 函数之间的空行 函数内部的空行l 【规则5-1-3】相对独立的程序块之间、变量说明之后必须加空行。if (!is_lock_card_succ). / program codeGetLockPhoneInfo(&st_lock_phone_info

22、);if (!is_lock_card_succ). / program code/空格GetLockPhoneInfo(&st_lock_phone_info); 不规范代码 规范代码5.2代码行l 【规则5-2-1】一行代码只做一件事情，如只定义一个变量，或只写一条语句。这样的代码容易阅读，并且方便于写注释。l 【规则5-2-2】if、for、while、do等语句自占一行，执行语句不得紧跟其后。不论执行语句有多少都要加。这样可以防止书写失误。int width, height, depth;/ 宽度高度深度int width; / 宽度int height;/ 高度int dep

23、th;/ 深度X a + b; y = c + d; z = e + f;x = a + b;y = c + d;z = e + f;if (width < height) dosomething();if (width < height) dosomething();for (initialization; condition; update) dosomething();other();for (initialization; condition; update)dosomething();/ 空行other();不规范代码 规范代码5.3代码行内的空格说明：空格的目的在于更清

24、晰的代码。l 【规则5-3-1】关键字之后要留空格。const、static等关键字之后至少要留一个空格，否则无法辨析关键字；if、for、while、switch等关键字之后应留一个空格再跟左括号(，以突出关键字。l 【规则5-3-2】函数名之后不要留空格，紧跟左括号(，以与关键字区别。l 【规则5-3-3】(向后紧跟，)、,、;向前紧跟，紧跟处不留空格。l 【规则5-3-4】,之后要留空格，如Function(x, y, z)。如果;不是一行的结束符号，其后要留空格，如for (initialization; condition; update)。l 【规则5-3-5】赋值操作符、比较操作

25、符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、“|”、“<<”,“”等二元操作符的前后应当加一个空格。l 【规则5-3-6】一元操作符如“!”、“”、“+”、“-”、“&”（地址运算符）等前后不加空格。l 【规则5-3-7】象“”、“.”、“->”这类操作符前后不加空格。l 【建议5-3-1】对于表达式比较长的for语句和if语句，为了紧凑起见可以适当地去掉一些空格，如for (i=0; i<10; i+)和if (a<=b) && (c<

26、=d)void Func1(int x, int y, int z);void Func1 (int x,int y,int z);if (year >= 2000)if(year>=2000)if (a>=b) && (c<=d)if (a >= b) && (c <= d)if(a>=b&&c<=d)for (i = 0; i < 10; i+)for (i=0; i<10; i+)for(i=0;i<10;i+)x = a < b ? a : b;x=a<b?a:

27、b;i+;int *x = &y;i +;int * x = & y; array5 = 0;a.Function();b->Function();array 5 = 0;a . Function();b -> Function();良好风格 不良风格5.4对齐缩进l 【规则5-4-1】程序块要采用缩进风格编写。l 【规则5-4-2】对齐使用TAB键，TAB键宽度设置为4个空格。说明：应注意使用不同编辑器时，TAB键设置不同造成的排版不同；应注意某些编辑器在识别、显示TAB键上存在问题；最终排版应以在项目的主代码编辑器（如VC、Source Insight等）中显示

28、一致统一、整洁清晰为准。Source Insight中设置：Options->Doucument Options->“Tab Width:4”l 【规则5-4-3】函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case语句下的情况处理语句也要遵从语句缩进要求。l 【规则5-4-4】程序块的分界符（如和）应各独占一行并且位于同一列，同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。for (.) . / program codefor (.

29、) . / program codeif (.) . / program code if (.) . / program codevoid example_fun( void ) . / program code void example_fun( void ) . / program code不规范代码 规范代码l 【规则5-4-5】预处理指令不需要缩进，总是从行首开始。即使预处理指令位于缩进代码块中，指令也应从行首开始。/ 良好风格：预处理指令均从行首开始 if (lopsided_score) #if DISASTER_PENDING / Correct - Starts at begi

30、nning of line DropEverything();#if NOTIFY NotifyClient();#endif#endif BackToNormal(); / 不良风格：缩进的预处理指令 if (lopsided_score) #if DISASTER_PENDING / Wrong! The "#if" should be at beginning of line DropEverything(); #endif / Wrong! Do not indent "#endif" BackToNormal(); 5.5长行拆分l 【规则5-

31、5-1】代码行最大长度宜控制在100至110个字符以内。代码行不要过长，否则眼睛看不过来，也不便于打印。l 【规则5-5-2】较长的语句（>110字符）要分成多行书写；长表达式要在低优先级操作符处拆分成新行，操作符放在新行之首（以便突出操作符）。拆分出的新行要进行适当的缩进，使排版整齐，语句可读。l 【规则5-5-3】循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分. 长表达式要在低优先级操作符处划分新行，操作符放在新行之首。l 【规则5-5-4】若函数或过程中的参数较长，则要进行适当的划分。if (very_longer_variable1 >= very_longe

32、r_variable12)&& (very_longer_variable3 <= very_longer_variable14)&& (very_longer_variable5 <= very_longer_variable16) dosomething();virtual CMatrix CMultiplyMatrix (CMatrix leftMatrix, CMatrix rightMatrix);for (very_longer_initialization; very_longer_condition; very_longer_upda

33、te)dosomething();report_or_not_flag = (taskno < MAX_ACT_TASK_NUMBER) && (n7stat_stat_item_valid (stat_item) && (act_task_tabletaskno.result_data != 0);n7stat_str_compare(BYTE *) & stat_object, (BYTE *) & (act_task_tabletaskno.stat_object), sizeof (_STAT_OBJECT);长行的拆分6.注释规范

34、6.1通用规则l 【规则6-1-1】一般情况，需要保证程序有一定的注释。必须保证关键的函数、流程、类型定义、变量等有相应注释说明。说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、。l 【规则6-1-2】注释应当准确、易懂，防止注释有二义性。说明：错误的注释不但无益反而有害。l 【规则6-1-3】除非能使用准确的英文表达，则使用中文注释。l 【规则6-1-4】避免在注释中使用缩写，特别是非常用缩写。说明：在使用缩写时或之前，应对缩写进行必要的说明。l 【规则6-1-5】需要为代码中使用的缩写增加注释,文件引入的新缩写必须在文件头部加以

35、说明。l 【规则6-1-6】通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。l 【规则6-1-7】注释格式尽量统一。建议使用/进行注释，多行注释可使用“/* */”。6.2文件注释l 【规则6-2】源文件（包含.h头文件、.c源文件及各种脚本文件等）头部应进行注释，应列出：版权说明、文件名、文件目的/功能，作者、创建日期等；如果源文件引入了新的缩写，则必须在文件头部注释说明。文件注释格式定义如下（可以不局限于该格式中定义的内容，但必须包含该格式中定义的内容）：/* Copyright

36、 (C) 2010-2011, XXX Co. Ltd.* All rights reserved.* FileName: / 文件名称* Description: / 文件描述* Author: / 作者* Date: / 创建时间* Others: / 其它说明*/* Abbreviation: / 如果文件引入了新的缩写，则必须在此处加以说明*/举例如下：/* Copyright (C) 2010-2011, XXX Co. Ltd.* All rights reserved.* FileName: starlib_nvset.h* Description: NV参数配置源文件* Aut

37、hor: zc* Date: 2010/4/13* Others: */*Abbreviation:NCM: Net Choose Menu 网络选择菜单VBC: Voice Broadcast 语音播报 */6.3函数注释l 【规则6-3】函数头部应进行注释，需要列出函数的功能、参数、返回值等。函数注释格式定义如下（可以不局限于该格式中定义的内容，但必须包含该格式中定义的内容）：/*/ Function: / 函数名称/ Description: / 函数功能描述/ Param: / 参数说明，包括参数的作用、取值范围等，格式如下：/ param1: 输入输出类型IN/OUT/INOUT 说

38、明/ param2: 输入输出类型IN/OUT/INOUT 说明/ / Return: / 函数返回值说明/ Others: / 其它说明/ Author: / 作者/*/举例如下：/*/ Function: StarLib_SetIdleNetIconType/ Description: 设置待机界面网络图标/ PARAM: icon:IN待机界面网络图标/ Return: 设置成功 = STARLIB_TRUE/ 设置失败 = STARLIB_FALSE/ Others: / Author: zc/*/6.4数据注释l 【规则6-4-1】对于所有有物理含义的变量、常量，如果其命名不是充分自

39、注释的，在声明时都必须加以注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。/ active statistic task number#define MAX_ACT_TASK_NUMBER 1000#define MAX_ACT_TASK_NUMBER 1000 / active statistic task numberl 【规则6-4-2】数据结构声明(包括结构体、枚举、类等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置；对结构中每个域的注释放在该域的右方。/ sccp interface with sccp user primit

40、ive message name enum SCCP_USER_PRIMITIVE N_UNITDATA_IND, / sccp notify sccp user unit data come N_NOTICE_IND, /* sccp notify user the No.7 network can not transmission this message*/ N_UNITDATA_REQ, / sccp user's unit data transmission request;l 【规则6-4-3】全局变量必须有注释，包括对其功能、取值、及其他注意事项等的说明。/标志是否通过锁卡流程；TURE = 通过锁卡流程，FALSE = 锁卡流程失败PUBLIC BOOLEAN g_isLockCardPass = FALSE;6.5代码注释l 【规则6-5-1】边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除！l 【规则6-5-2】如果代码本来就是清楚的，则不必加注释