软件开发规范.doc

《软件开发规范.doc》由会员分享，可在线阅读，更多相关《软件开发规范.doc（14页珍藏版）》请在三一文库上搜索。

1、软件开发规范(C#)文档名称软件开发规范初稿描述编写人员审核人版本日期文档变更历史时间修改人章节描述目 录1. 目的12. 范围23. 注释规范24. 命名总体规则35. 命名规范46. 编码规则87. 编程准则108. 代码包规范119. 源代码的管理1210. 输入控制校验规则1211. 数据库开发规则121. 目的为了统一公司软件开发的设计过程中关于代码编写时的编写规范和具体开发工作时的编程规范，保证代码的一致性，便于交流和维护，特制定此规范。2. 范围本规范适用于开发组全体人员，作用于软件项目开发的代码编写阶段和后期维护阶段。3. 注释规范3.1.概述a) 注释要求中文及中文的标点符号

2、b) 注释中，应标明对象的完整的名称及其用途，但应避免对代码过于详细的描述。c) 每行注释的最大长度为100个字符。d) 将注释与注释分隔符用一个空格分开。e)不允许给注释加外框。f)编码的同时书写注释。g)重要变量必须有注释。h)变量注释和变量在同一行，所有注释必须对齐，与变量分开至少两个空格。如：string title; / 标题i)典型算法必须有注释。j)在循环和逻辑分支地方的上行必须就近书写注释。k)程序段或语句的注释在程序段或语句的上一行l)在代码交付之前，必须删掉临时的或无关的注释。m)为便于阅读代码，每行代码的长度应少于100个字符。3.3. 模块（类）注释模块开始必须以以下

3、形式书写模块注释：/说明：/作者：作者中文名/创建时间：/ / 修改记录：/ 2012-01-01 修改人名称 修改功能描述/ 2012-01-02 修改人名称 修改功能描述/ 2012-01-03 修改人名称 修改功能描述public class Order3.4. 类属性注释在类的属性必须以以下格式编写属性注释： / / 属性说明 / public DateTime AddTime;3.5. 方法注释在类的方法声明前必须以以下格式编写注释/ / 方法说明/ / 参数说明/ 对方法返回值的说明，该说明必须明确说明返回的值代表什么含义/ 修改记录：/ 2012-01-01 修改人名称 修改描述

4、/ 2012-01-02 修改人名称 修改描述/ 2012-01-03 修改人名称 修改描述public int Add (OrderInfo model) 3.6. 代码间注释代码间注释分为单行注释和多行注释：单行注释：/多行注释：/* 多行注释1 多行注释2 多行注释3 */或者/多行注释1/ 多行注释2/ 多行注释3代码中遇到语句块时必须添加注释（if,for,foreach,）,添加的注释必须能够说明此语句块的作用和实现手段（所用算法等等）。具体可参考XML 文档注释（C# 编程指南）4. 命名总体规则 名字应该能够标识事物的特性，是有意义的，描述性的词语。能够一眼看出它作什么。别使用

5、会引起误解的名字。如果名字一目了然，就无需用文档来解释方法的功能了。 名字尽量使用英文单词。 名字尽量不使用缩写，除非它是众所周知的。 名字可以有两个或三个单词组成，但不应多于三个，控制在3至30个字母以内。 在名字中，多个单词用大写第一个字母（其它字母小写）来分隔。例如：IsSuperUser。 名字尽量使用前缀而不是后缀。 名字中的单词尽量使用名词，如有动词，也尽量放在后面。例如：FunctionUserDelete（而不是FunctionDeleteUser）。在具体任务开发中，如果有特定的命名约定，则在相应的软件开发计划中予以明确定义及上报。5. 命名规范具体可参考微软命名规范5.1.

6、 命名规范样式的分类名称解释例子Pascal规则首字母和后面的每个单词的首字母都大写；其他字母小写HelloWorldCamel规则首字母小写，而后面的每个单词的首字母大写；其他字母小写helloWorld Upper规则所有字母都大写，中间用下划线分隔 PI标识符命名格式例子备注标识符、参数、局部变量Camel规则public int GetTypeID(string typeName) int typeID; Private、Protected的实例字段Camel规则private string redValue;protected bool isOk;界面控件Camel规则private

7、 Label lblAlarm;缩写Upper规则namespace System.IO 缩写必须是被普遍接受、众所周知的缩写除上面的标识符外（包括但不限于：类名、方法名、命名空间）Pascal规则public System.Drawing.Color BackColor 5.2. 命名原则a) 有意义的，描述性的词语来命名。能够一眼看出它作什么。别使用会引起误解的名字。如果名字一目了然，就无需用文档来解释方法的功能了。b) 名字尽量不使用缩写，除非它是众所周知的。 c) 名字尽量使用英文单词，特殊情况下才使用拼音。d). 除用于循环，别使用单个字母的变量象i, n, x 等. 而要使用 in

8、dex, temp等。for ( int i = 0; i count; i ) .e) 类命名规则类名应该为名词及名词短语，尽可能使用完整的词.使用Pascal规则。不要使用类前缀 - 。不要使用下划线字符 (_)。不要使用任何类前缀（比如C）。有时候需要提供以字母 I 开始的类名称，虽然该类不是接口。只要 I 是作为类名称组成部分的整个单词的第一个字母，这便是适当的。例如，类名称 IdentityStore 就是适当的。在适当的地方，使用复合单词命名派生的类。派生类名称的第二个部分应当是基类的名称。例如，ApplicationException 对于从名为 Exception 的类派生的类

9、是适当的名称，原因是 ApplicationException 是一种 Exception。请在应用该规则时进行合理的判断。例如，Button 对于从 Control 派生的类是适当的名称。尽管按钮是一种控件，但是将 Control 作为类名称的一部分将使名称不必要地加长。public class FileStream f) 接口命名规则接口名称应该为名词及名词短语或者描述其行为的形容词，尽可能使用完整的词. (Example： IComponent or IEnumberable)使用Pascal规则。使用字符I为前缀，并紧跟一个大写字母（即接口名的第一个字母大写）public interf

10、ace IComponent g) 枚举命名规则对于 Enum 类型和值名称使用 Pascal规则。 少用缩写。 不要在 Enum 类型名称上使用 Enum 后缀。public enum FileMode Create, CreateNew, Open, OpenOrCreate, Truncate h) 静态常量使用名词及名词短语命名规则使用Upper规则（全部大写，中间用下划线分隔）int PI = 3.1415926i) 参数及非常量变量命名举例使用描述性的命名，名称应该明确表达参数的意义及类型，优先满足参数的意义描述使用 Camel 规则不要对字段名或静态字段名应用前缀。具体说来，不要

11、对字段名称应用前缀来区分静态和非静态字段。例如，应用 g_ 或 s_ 前缀是不正确的。j) Web UI类的变量命名可以通过特定的规则加入前缀Type GetType (string typeName)使用Pascal规则k) 对方法名采用一致的动词/宾语或宾语/动词顺序。例如，将动词置于前面时，所使用的名称诸如 InsertWidget 和 InsertSprocket；将宾语置于前面时，所使用的名称诸如 WidgetInsert 和 SprocketInsert。推荐名称应该为动词或动词短语.例如Save，SaveCustomer，而不要使用CustomerSave 。不要在方法中重复类的

12、名称。例如，如果某个类已命名为 Book，则不要将某个方法称为 Book.CloseBook，而可以将方法命名为 Book.Close。l) 属性命名规则名称应该为名词及名词短语使用Pascal规则对于bool型属性或者变量使用Is（is）作为前缀，不要使用Flag后缀，例如应该使用IsDeleted,而不要使用DeleteFlagpublic enum Color . m) 集合命名规则名称应该为名词及名词短语使用Pascal规则名称后面追加“Collection”n) 事件命名规则event handlers命名使用 EventHandler 后缀.两个参数分别使用 sender 及 e使

13、用Pascal规则事件参数使用EventArgs 后缀事件命名使用语法时态反映其激发的状态，例如 Changed，Changing.考虑使用动词命名.public delegate void MouseEventHandler(object sender, MouseEvent e);public class MouseEventArgs : EventArgs int x; int y; public MouseEventArgs(int x, int y) this.x = x; this.y = y; public int X get return x; public int Y get

14、 return y; 6. 编码规则6.1. 错误检查规则a) 编程中要考虑方法的各种执行情况，尽可能处理所有流程情况。b) 检查所有的系统调用的错误信息，除非要忽略错误。c) 将方法分两类：一类为与屏幕的显示无关， 另一类与屏幕的显示有关。对于与屏幕显示无关的方法，方法通过返回值来报告错误。对于与屏幕显示有关的方法，方法要负责向用户发出警告，并进行错误处理。d) 错误处理代码一般放在方法末尾。e) 对于通用的错误处理，可建立通用的错误处理方法，处理常见的通用的错误。6.2. 大括号规则将大括号放置在关键词下方的同列处，例如：if (条件表达式)while (条件表达式) . . 6.3. 缩

15、进规则使用一个两个空格为每层次缩进。例如：void func() if (false) if (true) while (false) 6.4 小括号规则a) 不要把小括号和关键词（if 、while等）紧贴在一起，要用空格隔开它们。b) 不要把小括号和方法名紧贴在一起。c) 除非必要，不要在Return返回语句中使用小括号。因为关键字不是方法，如果小括号紧贴着方法名和关键字，二者很容易被看成是一体的。6.5 if else规则如果你有用到else if 语句的话，通常最好有一个else块以用于处理未处理到的其他情况。可以的话放一个记录信息注释在else处，即使在else没有任何的动作。其格式

16、为：if (条件1) / 注释 else if (条件2) / 注释 else / 注释 注：if 和循环的嵌套最多允许4层6.6 比较规则总是将恒量放在等号/不等号的左边。一个原因是假如你在等式中漏了一个等号，语法检查器会为你报错。第二个原因是你能立刻找到数值而不是在你的表达式的末端找到它。例如：if ( 6 = errorNum ) .6.7 Case规则default case总应该存在，如果不允许到达，则应该保证：若到达了就会触发一个错误。Case的选择条件最好使用int或string类型。6.8 对齐规则变量的申明和初始化都应对齐。例如： int m_iCount; int i,j;

17、 float m_fIncome,m_fPay; m_iCount = 0; i = 1; m_fIncome = 0.3;6.9 单语句规则除非这些语句有很密切的联系，否则每行只写一个语句。6.10 单一功能规则原则上，一个程序单元（方法）只完成一项功能。6.11 简单功能规则原则上，一个程序单元的代码应该限制在一页内（2530行）。6.12 独立赋值规则嵌入式赋值不利于理解程序，同时可能回造成意想不到的副作用，应尽量编写独立的赋值语句。例如：使用“a = b + c ; e = a + d;”而不用“e = ( a = b + c ) + d ”。6.13 定义常量规则对于代码中引用的常量

18、尤其是数字），应该申明一個const常量，在代码中引用名字而不直接引用值。6.14 模块化规则某一功能，如果重复实现一遍以上，即应考虑模块化，将它写成通用方法。并向小组成员发布。同时要尽可能利用其它人的现成模块。6.15 交流规则共享别人的工作成果，向别人提供自己的工作成果。在具体任务开发中，如果有其它的编码规则，则在相应的软件开发计划中予以明确定义。6.16 当一个页面完成时，建议点击 （或按Ctrl+E,D）重新编排文档。（备注：这适用于大部分文档类型，如html页面、cs页面、样式表等）6.17 建议当一个类页面完成时，应点击右键，选择“组织 using”,点击“移除未使用的 usin

19、g”。6.18编写代码时如要将数据类型转换，建议使用系统自定义的数据转换类进行相关转换，以免发生异常。7. 编程准则7.1 变量使用a)一个变量只能有一个用途；变量的用途必须和变量的名称保持一致。b)变量定义就近原则。7.2 数据库操作a) 查找数据库表或视图时，建议只取出确实需要的那些字段，尽量避免使用*。b) 使用无关联子查询，而不要使用关联子查询。c) 清楚明白地使用列名，而不能使用列的序号。d) 用事务保证数据的完整性。e) 在Sql语句中使用除法时，为避免遇到以零作除数错误，建议除数写法为NULLIF(除数,0)。7.3 对象使用a) 尽可能晚地创建对象，并且尽可能早地释放它。7.4

20、 模块设计原则。a) 不允许随意定义公用的方法和类。b) 方法功能单一，不允许一个方法实现两个及两个以上的功能。c) 尽量不要在方法内部使用全局变量，如要使用全局变量，应转化为参数带入。d) 方法与方法之间只允许存在包含关系，而不允许存在交叉关系。即两者之间只存在单方向的调用与被调用，不存在双向的调用与被调用。e) 模块与模块之间尽量为松耦合。7.5 结构化要求a) 禁止出现两条等价的支路。例如：void func() if (a = 2) / else if (a = 3) / else if (a = 2) / else / b) 避免使用goto语句c) 用 CASE 实现多路分支d)

21、 不使用条件赋值语句。e) 避免不必要的分支。7.6 方法返回值原则1） 方法返回值使用bool类型：该方法只需要获得成功或者失败的返回信息时候使用int 类型：错误代码用负数表示，成功返回07.7. 使用region提高代码的可读性。比如：#region 描述区域所实现的功能/代码区域#endregion8. 代码包规范本项目中，每个任务在完成一个稳定的版本后，都应打包并且归档。8.1 代码包的版本号 项目中，代码包的版本号由圆点隔开的两个数字组成，第一个数字表示发行号，第二个数字表示该版的修改号。具体用法如下：1) 当代码包初版时，版本号为 V1.00；2) 当代码包被局部修改或bug修正

22、时，发行号不变，修改号第二个数字增1。例如，对初版代码包作了第一次修订，则版本号为 V1.01；3) 当代码包在原有的基础上增加部分功能，发行号不变，修改号第一个数字增1，例如，对V1.12版的基础上增加部分功能，则新版本号为 V1.20；4) 当代码包有重要修改或局部修订累积较多导致代码包发生全局变化时，发行号增1。例如，在 V1.15 版的基础上作了一次全面修改，则新版本号为 V2.00。8.2 代码包的标识 本项目所产生的代码包都有唯一、特定的编码，其构成如下：S-项目标识-代码包类型-版本号/序号 其中：1) S：本项目的标识，表明本项目是“XXXX”。2) 项目标识：简要标识本项目，

23、此标识适用于整个项目的文档。3) 代码包类型：取自以下表的两位字母编码。4) 版本号：本代码包的版本号。5) 序号：四位数字编码，指明该代码包在项目代码库的总序号。 例如：一个Windows下RAR源码的压缩代码包命名为： S-XXXX-WS-V1.02/0001项目的代码包分类表类 型编 码注 释RAR包（Windows）源码文件WS源代码文件包编译文件WB编译文件包安装文件WI安装文件包源码代码 + 安装文件WA源代码和安装文件包项目中所有代码包的标识清单将在项目开发计划中予以具体定义。9. 源代码的管理9.1. 代码库/目录的建立项目负责人在VSS中建立项目的文档库目录，即为“OldVe

24、rsion”目录，以便快速查询。9.2. 代码归档所有代码在完成一个稳定的版本后，项目负责人都应打包后，存放于VSS中该项目的“OldVersion”目录下，并且依据代码包的命名规范为代码包分配一个唯一名称。并在VSS中将项目打上版本标签，以便以后获取。9.3. 每天下班前要尽量把文件签入。9.4. 签出项目文件或解决方案时尽快签入，以免其他人员无法签出。9.5. 建议每天上班后立即获取最新版本，重新生成一次。9.6. 禁止将未编译通过的代码签入。9.7. 建议签入文件时填写注释，简要说明本次修改的内容。10. 输入控制校验规则10.1 数据录入控制a) TextBox输入1、要保持用户输入和

25、数据库接收的长度一致2、必须用系统自定义的过滤方法进行非法字符过滤，特殊格式要进行输入合法性校验。如：E_mail格式 XXXXXX.XXX. 电话格式 020-12345678 (020)12345678 邮政编码是六位11. 数据库开发规则11.1. 数据表表名使用Pascal规则，尽量不使用下划线，字段名称也使用Pascal规则。11.2. 必须建立数据库字典，字典中每张数据表都必须取一个相应中文名称，名称必须是唯一的，表中字段要取相应的中文名称，要有相应的中文注释来说明用途和规则。11.3. 在Sql语句中使用除法时，为避免遇到以零作除数错误，建议除数写法为NULLIF(除数,0)。1

26、1.4. 在编写视图时要用列名，禁止使用*。（如：要用Select ID,OrderId From Order,而不能用Select * From Order）。11.5. 查找数据库表或视图时，建议只取出确实需要的那些字段，尽量避免使用*。11.6. 使用无关联子查询，而不要使用关联子查询。11.7. 用事务保证数据的完整性。附录1：服务器控件名缩写表 a、web控件web控件名缩写AdRotatorartButtonbtnCalendarcalCheckBoxcbCheckBoxListcblCompareValidatorcpvCustomValidatorctvDataGriddgDa

27、taListdlDropDownListddlHyperLinkhlImageimgImageButtonibtnLabellblLinkButtonlbtnListBoxlbPanelplPlaceHolderphRadioButtonrbRadioButtonListrblRangeValidatorrvRegularExpressionValidatorrevRepeaterrptRequiredFieldValidatorrfvTabletblTableCelltclTableRowtrTextBoxtxtValidationSummaryvsXMLxml b、html控件html控件

28、名缩写HtmlAnchorhahHtmlButtonhbtnHtmlFormhfrmHtmlGenericControlhgcHtmlImagehimgHtmlInputButton（按钮）htxtHtmlInputButton（重置）hrbtnHtmlInputButton（提交）hsbtnHtmlInputCheckBoxhicbHtmlInputFilehfileHtmlInputHiddenhhdnHtmlInputImagehiimgHtmlInputRadioButtonhrbHtmlInputText（密码）hpwdHtmlInputText（文本）htxtHtmlSelecthsltHtmlTablehtabHtmlTableCellhtclHtmlTableRowhtrHtmlTextAreahtxta