程序员开发手册

1、安全生产信息化管理系统程序员开发手册1 概述1.1 目的1、方便代码的交流和维护。2、 不影响编码的效率，不与大众习惯冲突。3、 使代码更美观、阅读更方便。4、 使代码的逻辑更清晰、更易于理解。1.2 范围本手册适用于开发部全体人员，作用于软件项目开发的代码编写阶段和后期维护阶段。1.3 警示通过自动检查【Microsoft.StyleCop 】或人工检查【部门主管或相关负责人】不符合编码规范的，必须在限期【部门主管或相关负责人指定时间】内修正 ， 逾 期视为工作过失，部门主管或相关负责人视具体情况做出相关处理。1.4 术语定义1、 匈 牙利命名法【禁用】标识符的名字以一个或者多个小写字母开头

2、作为前缀；前缀之后的是首字母大写的一个单词或多个单词组合，该单词要指明变量的用途。例如： aUserld 数组 (Array) 定义以小写字母a 开头2、 帕 斯卡 ( pascal )命名法【推荐】将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用 Pascal 大小写。例如：UserId3、 骆驼(Camel)命名法【推荐】标识符的首字母小写，而每个后面连接的单词的首字母都大写。例如：userId2 代码格式2.1 列宽1、 为 了防止在阅读代码时不得不滚动源代码编辑器，每行代码或注释在一般显示频率下不得超过一显示屏，代码列宽控制在110 字符左右。2、

3、 系 统中部分代码可以不遵循此原则。如：VIWFormltemDeta 叩 dv =(VIWFormltemDeta 叩 ) MHelper.SQLComma nd.query(sql,VIWFormltemDetail.TName, sqIParams);3、SQL语句拼接、字符串拼接、函数参数名过长、判断语句过长的代码要遵循以上原则。2.2 换行1、 当 表达式超出或即将超出规定的列宽，一行被分为几行时，通过将串联运算符放在每一行的末尾而不是开头，清楚地表示没有后面的行是不完整的。Stri ng querySql =“ SELECTProjectId ” + “ ,ProjectTitle

4、 ” + “ FROM Project ”2、 每 一行上放置的语句避免超过一条。3、 当 表达式超出或即将超出规定的列宽，遵循以下规则进行换行(1) 在逗号前换行。(2) 在操作符前换行。(3) 规 则 1 优先于规则2。例如：StringBuilder querySql = new StringBuilder();querySql.Appe nd("SELECT a.ProjectId AS PK ");querySql.Appe nd(",a.ProjectTitle");querySql.Appe nd(",a.ProjectDispl

5、ayCode");querySql.Appe nd(",a.lsb nCode AS ISBNCode");querySql.Appe nd("FROM Project a ");当以上规则会导致代码混乱的时候自己采取更灵活的换行规则。2.3 缩进缩进应该是每行一个 Tab(4个空格)，不要在代码中使用 Tab字符。Visual Studio.Net 设置：工具-> 选项-> 文本编辑器->C#->制表符-> 插入空 格2.4 空行空行是为了将逻辑上相关联的代码分块，以便提高代码的可阅读性。在以下情况下使用两个空行

6、1、 接口和类的定义之间。2、 枚举和类的定义之间。3、 类与类的定义之间。在以下情况下使用一个空行1、 方法与方法、属性与属性之间。2、 方法中变量声明与语句之间。3、 方法与方法之间。4、 方法中不同的逻辑块之间。5、 方法中的返回语句与其他的语句之间。6、 属性与方法、属性与字段、方法与字段之间。7、注释与它注释的语句间不空行，但与其他的语句间空一行。2.5 空格在以下情况中要使用到空格1、 关键字和左括符“ ( ”应该用空格隔开。如while (true)注意 ; 在方法名和左括符“ ( ”之间不要使用空格，这样有助于辨认代码中的方法调用与关键字。多个参数用逗号隔开，每个逗号后都应加一

7、个空格。2、 除了 . 之外，所有的二元操作符都应用空格与它们的操作数隔开。一元操作符、+及 - 与操作数间不需要空格。如a+=c+d;a = (a + b) / (c * d);while(d+ = s+)n+;PrintSize( “ size is “ +size+ “ n” ) ；3、 语句中的表达式之间用空格隔开。女口for(expr1; expr2; expr3)4、 以下写法是不允许的：int j=i+k;2.6 括号 -()1、 左括号“( ”不要紧靠关键字，中间用一个空格隔开2、 左括号“( ”与方法名之间不要添加任何空格。3、 没有必要的话不要在返回语句中使用() 。如if

8、 (con diti on)Array.Remove(1)return 12.7 花括号 -1、 左花括号“ ”放于关键字或方法名的下一行并与之对齐。如if (con diti on)public int Add(i nt x, int y)2、 左花括号“ ”要与相应的右花括号 “ ”对齐。3、 通常情况下左花括号“ ”单独成行，不与任何语句并列一行。4、if、while、do语句后一定要使用,即使号中为空或只有一条语句。如if(somevalue =1)somevalue = 2;右花括号“”后建议加一个注释以便于方便的找到与之相应的。如while(1)if (valid) / if va

9、lidelse / n ot valid / end forever以下情况是不允许的：if(x=0) Resp on se.Write (”用户编号必须输入！"); 或者：if(x=0) Respo nse.Write(" 用 户编号必须输入！");2.8 分解将大的复杂代码节分为较小的、易于理解的模块。2.9 SQL1、 编写SQL语句时，对于关键字或保留字使用全部大写，对于数据库元素(如表、列和视图等命名) 使用帕斯卡命名法命名。如：SELECT UserId AS EmId FROM UserSELECT UserId AS EmId FROM User

10、AS emSELECT UserId AS EmId FROM User AS EM等允许使用；2、将每个主要的SQL子句放在不同的行上，这样更容易阅读和编辑语句。例如： SELECT FirstName, LastNameFROM CustomersWHERE State = 'WA'3、 不要从数据表中调用页面或程序不需要的字段；2.10 弓 | 用1、对于程序中字段名称的引用要通过对应的属性调用实现。如：Int userid = (int)DvO“ Userid ” ; 是不允许的；Int userid = (in t)Dv0User.x.Userld.Colum nN

11、ame;是允许的 ;stri ng bookPriceName = Book.x.BookPrice.Colu mnN ame;decimal? bookPrice = nu II;if(drbookPriceName != DBNull.Value)bookPrice = (decimal)drbookPriceName;是允许的；3 程序注释3.1 注释概述1、 修改代码时，总是使代码周围的注释保持最新。2、 在每个例程的开始，提供标准的注释样本以指示例程的用途、假设和限制很有帮助。注释样本应该是解释它为什么存在和可以做什么的简短介绍。3、 避免在代码行的末尾添加注释；行尾注释使代码更难阅

12、读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释在公共制表位处对齐。4、 避免杂乱的注释，如一整行星号。而是应该使用空白将注释同代码分开。5、 避免在块注释的周围加上印刷框。这样看起来可能很漂亮，但是难于维护。6、 在部署发布之前，移除所有临时或无关的注释，以避免在日后的维护工作中产生混乱。7、 如果需要用注释来解释复杂的代码节，请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码，而应该重写它。尽管一般不应该为了使代码更简单以便于人们使用而牺牲性能，但必须保持性能和可维护性之间的平衡。8、 在编写注释时使用完整的句子。注释应该阐明代码，而不应该增加多义性。

13、9、 在编写代码时就注释，因为以后很可能没有时间这样做。另外，如果有机会复查已编写的代码，在今天看来很明显的东西六周以后或许就不明显了。10、 避免多余的或不适当的注释，如幽默的不主要的备注。11、 使用注释来解释代码的意图。它们不应作为代码的联机翻译。12、 注释代码中不十分明显的任何内容。13、 为了防止问题反复出现，对错误修复和解决方法代码总是使用注释，尤其是在团队环境中。14、 对由循环和逻辑分支组成的代码使用注释。这些是帮助源代码读者的主要方面。15、 在整个应用程序中，使用具有一致的标点和结构的统一样式来构造注释。16、 用空白将注释同注释分隔符分开。在没有颜色提示的情况下查看注释

14、时，这样做会使注释很明显且容易被找到。17、 在所有的代码修改处加上修改内容的注释（此项只供参考）。18、 对于常量、变量、表达式等使用单行注释时建议放到声明的后面；19、 对 于常量、变量、表达式等建议使用单行注释，单行注释格式如：private int nu mber; / 注释语句或：/ 注释语句private int nu mber;20、 为了使层次清晰，在闭合的右花括号后注释该闭合所对应的起点（此项只供参考）。n amespace Lan gchao.Procume nt.Web / n amespace Lan gchao.Procume nt.Web3.2 文档型注释该类注释采

15、用.Net 已定义好的Xml 标签来标记，在声明接口、类、方法、属性、字段都应该使用该类注释，以便代码完成后直接生成代码文档，让别人更好的了解代码的实现和接口。如 /<summary>MyMethod is a method in the MyClass class. /vpara>Here's how you could makea sec ond paragraph in a descripti on. /<see cref="System.Co nsole.WriteLi ne"/>/for in formati on about

16、 output stateme nts./</para>/vseealso cref="MyClass.Mai n"/>/</summary>public static void MyMethod(int Int1)又如：类属性注释规范在类的属性必须以以下格式编写属性注释：/ <summary>/ 属性说明/ </summary>方法注释规范在类的方法声明前必须以以下格式编写注释/ <summary>/ 说明：<对该方法的说明> / </summary>/ vparam name=&q

17、uot;< 参数名称>"><参数说明></param>/ vretur ns>/< 对方法返回值的说明，该说明必须明确说明返回的值代表什么含义 >/ </returns>3.3 类 c 注释 (此项只供参考)该类注释用于1、 不再使用的代码。2、 临时测试屏蔽某些代码。用法/* 修改标识 修改原因. (the source code )*/3.4 单行注释该类注释用于1、 方 法内的代码注释。如变量的声明、代码或代码段的解释。注释示例:/ <summary>/ 注释语句/ </summary&g

18、t;private int nu mber;或/ 注释语句private int nu mber;private int nu mber;注释语句2、方法内变M的声明或花括号后的注释，注释示例:if ( 1 = 1) / always truestateme nt; / always true3.5 文件注释文件功能描述只需简述，具体详情在类的注释中描述3.6 注释标签<c></c>为您提供了一种将说明中的文本标记 为代码的方法。使用 <code>text布望将其指示为代码的文本。将多行指示为代码<para><para>错误！超链接引

19、用无效。</para>content段洛文本。用于诸如<remarks>或<returns>等标记内，使您得以将结构添加到文本中。vparam>vparam name='错误!超链接 弓1用无效。' > 错误！超链接引用无效。</param>name为方法参数名。将此名称 用单引号括起来（”）。应当用于方法声明的注释中， 以描述方法的一个参数。vparamref>vparamref name="错误!超链接引用无效。"/>n ame要引用的参数名。将此名称用双<paramref&g

20、t;标记为您提供了一种 指小 词为参数的方法。可以处理XMUC件，从而用莫种独特的方法格式 化该参数。<see>引号括起来（""）。<see错误！超链接引用无 效。 错误！超链接引用无效。"member"/ >cref = "member"对可以通过当前编译环境进行调用的成 员或 字段的引用。编译器检查到给/£ 代码兀素存在后，将membe传 递给输出XML中的兀素名。必须 将member括在双引号（”"）中。使您得以从文本内指定链接。使用<seealso> 指小卅望在请参阅”

21、一节中出现的文本。<seealso>vseealso错误！超链接引用无效。错误！超链接引用无 效。"member"/ >cref = "member" 对可以通过当前编译环境进行调用的成 员或 字段的引用。编译器检查到给/£ 代码兀素存在后，将membe传 递给输出XML中的兀素名。必须 将member括在双引号（”"）中使您得以指定希望在“请参阅”一节中出现的文本。使用 <see>从文本<example>< example >错误！超链接引用无效。</example >

22、; description使用example标记可以指定使用方法或其他库成员的示例。一般情况下，这将涉及到< code >标记 的使用。<code>代码示例的说明。< code >错误！超链接引用无效。< /code >con te nt为布望将其标记为 代码的文本Q记为您提供了一种将多行指示为代码的方法。使用<c>才旨示应将说明中的文本标记为代码<summary>vsummary错误! 超链接引用无效。/summary止匕处description为对象的摘要。应当用于描述类型成员。使用< remarks >以

23、提供有关典型本身的信息。vexcepti on>vexception 错误!超链接弓1用无效。错误！超链接引用无vexcepti on > 标记使您 可 以指定类能够引发的异常。效。"member"*昔误！超链接 弓 用无效。v/exceptio n> cref = "member'对可从当前 编译环境中 获取的异常的引 用。编译器检查 到给定异常存在后，将member 转换为输出XML中的规范化元素 名。必须将membe拈在双引号 ("")中。descripti on 说明。<in clude><i

24、n clude>标记使您得以引用描<include file=' 错误!超链 接引用无效。'path='错误！超 链接引用无效。颂昔误！超链接 引用无效。="错误！超链接引用 无效。"'/> file name 包含文 档的文件 名。该文件名可用路径 加以限定。将file name括在单 引号中('')。Tagpath : file name 中指向 标述源代码中类型和成员的另一文 件中 的注释。这是除了将文档注释 宜接置于 源代码文件中之外的另 一种可选方法。<include>标记使用XMLXP

25、ath语法。有关自定义<include> 使 用的方法， 请参阅XPath文档。记名的标记路径。将此路径括在 单引号中('')。name注释前边的 标记中的名称说明符；名称具有 一个 id 。id位于注释之前的标记的id。将此 id括在双引号中("")。<list><list type="bullet" |"nu mber" | "table" ><listheader><term>错误！超链接引用无效。</term>vdesc

26、ription> 错误！超链接 弓I 用无效。v/descripti on></listheader><item><term>错误！超链接引用无效。</term><description> 错误!超链接 弓I 用无效。v/descripti on></item></list>term定义的项，该项将在text 中定义。descripti on 目符号歹U表或listheader块用于JE义表或JE 义列表中的标题行。定义表时，只 需为标题 中的项提供一个项。列表中的每一项用item块指JEo创

27、 建义列表时，既需要指JEterm也需要指/E text。但是，对 于表、项目符 号列表或编号列表，只需为text提供一个项。列表或表所拥有的item块数可以根 据需要而JEovpermissi on>vpermission 错误！超链接引用vpermissi on 标记使您得以将成 员无效。错误！超链接引用无效。"member"错误！超链接引用无效。v/permission>cref = "member"对可以通过当前编译环境进行调用的的访问记入文档。System.Security.Permissio nSet 使您得以指定对成员的访问。成

28、员或字段的引用。编译器检查 到给/£代码兀素存在后，将 membe转换为输出XML中的规范 化兀素名。必须将membe拈在 双引号("")中。descripti on 成员的访问的<remarks><remarks>错误!超链接引用无效。</remarks>descripti on成员 的说明。<remarks>标记是可以指定有关类或其他类型的概述桁息的位置。<summary>!可以描述该类型的 成员的位置。vretur ns><returns>错误！超链接引用无效。</returns>descripti on 返回值的说 明。<returns> 标记应当用于方法声明的注释，以描述返回值。<value><value&g