软件工程软件代码编程规范.docx
- 文档编号:24850027
- 上传时间:2023-06-02
- 格式:DOCX
- 页数:32
- 大小:29.47KB
软件工程软件代码编程规范.docx
《软件工程软件代码编程规范.docx》由会员分享,可在线阅读,更多相关《软件工程软件代码编程规范.docx(32页珍藏版)》请在冰豆网上搜索。
软件工程软件代码编程规范
软件代码编程规范
编号:
发布日期:
编制部门:
研发部
审核人:
批准人:
1.版本记录
序号
版本号
编制/修改
审核
批准
发布日期
主要修改记录
1
A0
首次生成
说明:
此表为内部文件的版本记录,各列均应填写。
2.目的
以C#代码为例,规范编码规则和注意事项,明确编程的各项要求,提高代码的可靠性、可读性、可修改性、可维护性、一致性、可再利用性等。
其它开发语言可参照执行。
3.适用范围
本标准规定了C#语言的编程规范,主要包括基本原则、布局、注释、命名规则、声明、表达式与语句、类与接口等。
本标准适用于使用C#、C++、VB.NET、JAVA等编程语言开发的软件,自生效之日起,对公司以后新编写的和修改的代码具有约束力。
4.术语定义
3.1原则
编程时应该坚持的指导思想。
3.2规则
编程时必须遵守的约定。
3.3建议
编程时必须加以考虑的约定。
3.4说明
编程时必须加以考虑的约定。
3.5正例
对此规则或建议给出的正确例子。
3.6反例
对此规则或建议给出的反面例子。
5.职责
研发部负责制定软件代码编程规范,并按照本规范进行代码编写。
6.工作程序
5.1基本原则
5.1.1原则1-1
首先是为人编写程序,其次才是计算机。
这是软件开发的基本要点,软件的生命周期贯穿产品的开发、测试、生产、用户使用、版本升级和后期维护等长期过程,只有易读、易维护的软件代码才具有生命力。
5.1.2原则1-2
保持代码的简明清晰,避免过分的编程技巧。
简单是最美。
保持代码的简单化是软件工程化的基本要求。
不要过分追求技巧,否则会降低程序的可读性。
5.1.3原则1-3
所有的代码尽量遵循公共语言规范(CLS)。
编程时以该规范为准,规范没有规定的内容参考上面的标准。
5.1.4原则1-4
编程时首先达到正确性,其次考虑效率。
编程首先考虑的是满足正确性、健壮性、可维护性、可移植性等质量因素,最后才考虑程序的效率和资源占用。
5.1.5原则1-5
尽量避免使用GOTO语句。
5.1.6原则1-6
尽可能重用、修正老的代码。
尽量选择可借用的代码,对其修改优化以达到自身要求。
5.1.7原则1-7
尽量减少同样的错误出现的次数。
事实上,我们无法做到完全消除错误,但通过不懈的努力,可以减少同样的错误出现的次数。
5.2布局
程序布局的目的是显示出程序良好的逻辑结构,提高程序的准确性、连续性、可读性、可维护性。
更重要的是,统一的程序布局和编程风格,有助于提高整个项目的开发质量,提高开发效率,降低开发成本。
同时,对于普通程序员来说,养成良好的编程习惯有助于提高自己的编程水平,提高编程效率。
因此,统一的、良好的程序布局和编程风格不仅仅是个人主观美学上的或是形式上的问题,而且会涉及到产品质量,涉及到个人编程能力的提高,必须要引起重视。
5.2.1基本格式
5.2.1.1规则2-1-1
源代码文件(.cs)的布局顺序是:
using语句、命名空间、注释、类。
以下内容如果某些节不需要,可以忽略。
但是其它节要保持该次序。
正例:
usingSystem;
namespacexxx
{
///
///内容摘要:
本类是…..,包括主要……模块、……函数及功能是…….
///完成日期:
输入完成日期,例:
2014年3月1日
///版本:
///作者:
///修改记录1:
修改历史记录,包括修改日期、修改者及修改内容
///修改日期:
///版本号:
///修改人:
///修改内容:
///
publicclassSample
{
}
}
5.2.1.2规则2-1-2
遵循统一的布局顺序来书写using语句,不同类别的using语句之间用空行分隔。
using命名空间语句的排列顺序为System开头的命名空间在最前面,接下来是引自外部的命名空间,再接下来是应用程序自身的命名空间,即using中标准的命名空间要在本地的命名空间之前,而且按照字母顺序排列。
正例:
usingSystem;
usingSystem.Data;
usingFarPoint.Win.Spread;
using.DSS.Public;
5.2.1.3规则2-1-3
程序中一行的代码和注释不能超过80列
包括空格在内不超过80列。
5.2.1.4规则2-1-4
if、else、elseif、for、while、do等语句自占一行,执行语句不得紧跟其后。
不论执行语句有多少都要加{}。
这样可以防止书写失误,也易于阅读。
正例:
if(varible1 { varible1=varible2; } 反例: 下面的代码执行语句紧跟if的条件之后,而且没有加{},违反规则。 //第三方的 //程序自身的 //.Net自身的 if(varible1 5.2.1.5建议2-1-5 源程序中关系较为紧密的代码应尽可能相邻 这样便于程序阅读和查找。 正例: iLength=10; iWidth=5; //矩形的长与宽关系较密切,放在一起。 StrCaption=“Test”; 反例: iLength=10; strCaption=“Test”; iWidth 5.2.2对齐 5.2.2.1规则2-2-1 如果使用TAB键,必须统一设定缩进为4个空格。 (VS2010默认) 消除不同编辑器对TAB处理的差异,有的代码编辑器可以设置用空格代替TAB键。 5.2.2.2规则2-2-2 程序的分界符‘{’和‘}’应独占一行并且位于同一列,同时与引用它们的语句左对齐。 {}之内的代码块使用缩进规则对齐。 这样使代码便于阅读,并且方便注释。 dowhile语句和结构的类型化时可以例外, while条件和结构名可与}在同一行。 正例: voidFunction(intiVar) { while(condition) { DoSomething(); } } 反例: voidFunction(intiVar){ while(condition){ DoSomething(); }} 5.2.2.3建议2-2-3 相关的赋值语句等号对齐。 正例: tPDBRes.wHead=0; tPDBRes.wTail=wMaxNumOfPDB-1; tPDBRes.wFree=wMaxNumOfPDB; tPDBRes.wAddress=wPDBAddr; tPDBRes.wSize=wPDBSize; 5.2.3空行空格 5.2.3.1规则2-3-1 不同逻辑程序块之间要使用空行分隔。 空行起着分隔程序段落的作用。 适当的空行可以使程序的布局更加清晰。 正例: voidHey(void) { [Hey实现代码] } //空一行 voidAck(void) { [Ack实现代码] } 反例: voidHey(void) { [Hey实现代码] } voidAck(void) { [Ack实现代码] } //两个函数的实现是两个逻辑程序块,应该用空行加以分隔。 5.2.3.2规则2-3-2 一元操作符如“! ”“~”“++”“--”“*”“&”等前后不加空格。 []、、、、、、“”“.”这类操作符前后不加空格。 正例: ! bValue ~iValue ++iCount &fSum aiNumber[i]=5; tBox.dWidth 5.2.3.3建议2-3-3 多元运算符和它们的操作数之间至少需要一个空格。 正例: fValue=fOldValue; fTotal+fValue iNumber+=2; 5.2.3.4建议2-3-4 关键字之后要留空格。 if、for、while等关键字之后应留一个空格再跟左括号‘(’,以突出关键字。 5.2.3.5规则2-3-5 函数名之后不要留空格。 函数名后紧跟左括号‘(’,以与关键字区别。 5.2.3.6规则2-3-6 ‘(’向后紧跟,、、‘)’‘,’‘;’向前紧跟,紧跟处不留空格。 ‘,’之后要留空格。 ‘;’不是行结束符号时其后要留空格。 正例: 例子中的凵代表空格。 for凵(i凵=凵0;凵i凵<凵MAX_BSC_NUM;凵i++) { DoSomething(iWidth,凵iHeight); } 5.2.3.7规则2-3-7 注释符与注释内容之间要用一个空格进行分隔。 正例: /*注释内容*/ //注释内容 反例: /*注释内容*/ //注释内容 5.2.4断行 5.2.4.1规则2-4-1 长表达式(超过120列)要在低优先级操作符处拆分成新行,操作符放在新行之首(以便突出操作符)。 拆分出的新行要进行适当的缩进,使排版整齐。 条件表达式的续行在第一个条件处对齐。 for循环语句的续行在初始化条件语句处对齐。 函数调用和函数声明的续行在第一个参数处对齐。 赋值语句的续行应在赋值号处对齐。 正例: if((iFormat==CH_A_Format_M) &&(iOfficeType==CH_BSC_M)) //条件表达式的续行在第一个条件处对齐 { DoSomething(); } for(long_initialization_statement; long_condiction_statement; long_update_statement) { DoSomething(); } //函数声明的续行在第一个参数处对齐 BYTEReportStatusCheckPara(BYTEucCallNo, BYTEucStatusReportNo); //赋值语句的续行应在赋值号处对齐 fTotalBill=fTotalBill+faCustomerPurchases[iID] +fSalesTax(faCustomerPurchases[iID]); 5.2.4.2规则2-4-2 函数声明时,类型与名称不允许分行书写。 正例: doubleCalcArea(doubledWidth,doubledHeight); 反例: double CalcArea(doubledWidth,doubledHeight); 5.3注释 注释有助于理解代码,有效的注释是指在代码的功能、意图层次上进行注释,提供有用、额外的信息,而不是代码表面意义的简单重复。 5.3.1规则3-1 类、方法、属性的注释采用XML文档格式注释。 代码间多行注释为: “/*…*/”,单行注释采用“//…”。 正例: publicclassSample { //数据成员(单行注释) privateintm_iProperty1; /// ///示例属性 /// publicintProperty1 { get { returnm_iProperty1; } /*set(多行注释) { m_iProperty1=value; }*/ } 5.3.2规则3-2 一般情况下,源程序有效注释量必须在20%以上。 注释的原则是有助于对程序的阅读理解,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。 有效的注释是指在代码的功能、意图层次上进行注释,提供有用、额外的信息。 5.3.3规则3-3 注释使用中文。 对于特殊要求的可以使用英文注释,如工具不支持中文或国际化版本时。 5.3.4规则3-4 类、接口头部应进行XML注释。 注释必须列出: 内容摘要、版本号、作者、完成日期、修改信息等。 正例: /// ///内容摘要: 本类的内容是….. ///完成日期: 2014年3月1日 ///版本: V1.0 ///作者: 某某 /// ///修改记录1: ///修改日期: 2014年3月10日 ///版本号: V1.2 ///修改人: 某某某 ///修改内容: 对方法……进行修改,修正故障BUG……。 ///修改记录2: ///修改日期: 2014年3月20日 ///版本号: V1.3 ///修改人: 某某某某 ///修改内容: 对方法……进行进一步改进,修正故障……。 /// 5.3.5规则3-5 公共方法前面应进行XML注释,列出: 函数的目的/功能、输入参数、返回值等。 5.3.6规则3-6 包含在{}中代码块的结束处应加注释,便于阅读。 特别是多分支、多重嵌套的条件语句或循环语句。 此时注释可以用英文,方便查找对应的语句。 正例: voidMain() { if(…) { … while(…) { … }/*endofwhile(…)*///指明该条while语句结束 … }/*endofif(…)*///指明是哪条语句结束 }/*endofvoidmain()*///指明函数的结束 5.3.7规则3-7 保证代码和注释的一致性。 修改代码同时修改相应的注释,不再有用的注释要删除。 5.3.8规则3-8 注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。 在使用缩写时或之前,应对缩写进行必要的说明。 正例: 如下书写比较结构清晰 /*获得子系统索引*/ iSubSysIndex=aData[iIndex].iSysIndex; /*代码段1注释*/ [代码段1] /*代码段2注释*/ [代码段2] 反例1: 如下例子注释与描述的代码相隔太远。 /*获得子系统索引*/ iSubSysIndex=aData[iIndex].iSysIndex; 反例2: 如下例子注释不应放在所描述的代码下面。 iSubSysIndex=aData[iIndex].iSysIndex; /*获得子系统索引*/ 反例3: 如下例子,显得代码与注释过于紧凑。 /*代码段1注释*/ [代码段1] /*代码段2注释*/ [代码段2] 5.3.9规则3-9 注释与所描述内容进行同样的缩排。 可使程序排版整齐,并方便注释的阅读与理解。 正例: 如下注释结构比较清晰 intDoSomething(void) { /*代码段1注释*/ [代码段1] /*代码段2注释*/ [代码段2] } 反例: 如下例子,排版不整齐,阅读不方便; intDoSomething(void) { /*代码段1注释*/ [代码段1] /*代码段2注释*/ [代码段2] } 5.3.10规则3-10 对分支语句(条件分支、循环语句等)必须编写注释。 这些语句往往是程序实现某一特殊功能的关键,对于维护人员来说,良好的注释有助于更好的理解程序,有时甚至优于看设计文档。 5.3.11建议3-1 通过对函数或过程、变量、结构等正确的命名以及合理地组织代码结构,使代码成为自注释的。 清晰准确的函数、变量命名,可增加代码的可读性,减少不必要的注释。 5.3.12建议3-2 尽量避免在注释中使用缩写,特别是不常用缩写。 在使用缩写时,应对缩写进行必要的说明。 5.4命名规则 好的命名规则能极大地增加可读性和可维护性。 同时,对于一个有上百个人共同完成的大项目来说,统一命名约定也是一项必不可少的内容。 本章对程序中的所有标识符(包括命名空间、变量名、常量名、控件名、参数名、属性名、方法名、类名、接口等)的命名做出约定。 5.4.1规则4-1 标识符要采用英文单词或其组合,便于记忆和阅读,切忌使用汉语拼音来命名。 标识符应当直观且可以拼读,可望文知义,避免使人产生误解。 程序中的英文单词一般不要太复杂,用词应当准确。 5.4.2规则4-2 标识符只能由26个英文字母,10个数字,及下划线的一个子集来组成,并严格禁止使用连续的下划线,下划线也不能出现在标识符头或结尾(预编译开关除外)。 5.4.3规则4-3 标识符的命名应当符合“min-length&&max-information”原则。 较短的单词可通过去掉“元音”形成缩写,较长的单词可取单词的头几个字母形成缩写,一些单词有大家公认的缩写,常用单词的缩写必须统一。 协议中的单词的缩写与协议保持一致。 对于某个系统使用的专用缩写应该在某处做统一说明。 正例: 如下单词的缩写能够被大家认可: temp可缩写为tmp; flag可缩写为flg; statistic可缩写为stat; increment可缩写为inc; message可缩写为msg; 规定的常用缩写如下: 常用词 缩写 Argument Arg Buffer Buf Clear Clr Clock Clk Compare Cmp Configuration Cfg Context Ctx Delay Dly Device Dev Disable Dis Display Disp Enable En Error Err Function Fnct Hexadecimal Hex HighPriorityTask HPT I/OSystem IOS Initialize Init Mailbox Mbox Manager Mgr Maximum Max Message Msg Minimum Min Multiplex Mux OperatingSystem OS Overflow Ovf Parameter Param Pointer Ptr Previous Prev Priority Prio Read Rd Ready Rdy Register Reg Schedule Sched Semaphore Sem Stack Stk Synchronize Sync Timer Tmr Trigger Trig Write Wr 5.4.4规则4-4 采用应用领域相关的术语来命名。 软件开发人员应注意软件用户的一些约定术语,不应当随意的创造术语,这会降低软件的易用性。 5.4.5规则4-5 程序中不要出现仅靠大小写区分的相似的标识符。 5.4.6规则4-6 用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。 说明: 下面是一些在软件中常用的反义词组。 add/remove;begin/end;create/destroy;insert/delete; first/last;get/release;increment/decrement;put/get; add/delete;lock/unlock;open/close;old/new; show/hide;start/stop;next/previous;min/max;up/down; source/target;send/receive;source/destination;cut/paste; 5.4.7规则4-7 常量名都要使用大写字母,用下划线‘_’分割单词。 正例: 如DISP_BUF_SIZE、MIN_VALUE、MAX_VALUE等等。 5.4.8规则4-8 一般变量名不得取单个字符(如i、j、k等)作为变量名,局部循环变量除外。 变量,尤其是局部变量,如果用单个字符表示,很容易出错(如l误写成1),而编译时又检查不出,则有可能增加排错时间。 过长的变量名会增加工作量,会使程序的逻辑流程变得模糊,给修改带来困难,所以应当选择精炼、意义明确的名字,才能简化程序语句,改善对程序功能的理解。 5.4.9规则4-9 使用一致的前缀来区分变量的作用域。 说明: 变量活动范围前缀规范如下: m_: 类的成员变量(属性所对应的变量) 空: 局部变量不加范围前缀 5.4.10规则4-10 使用一致的小写类型指示符作为前缀来区分变量的类型。 说明: 常用变量类型前缀列表如下: I: int F: float; d: double dcm: decimall ch: char l: long bt: byte sbt: sbyte b: bool sht: short usht: ushort ul: ulong ar: array str: string st: struct 以上前缀可以进一步组合,在进行组合时,数组类型的前缀指示符必须放在变量类型前缀的首位。 5.4.11规则4-11 完整的变量名应由前缀+变量名主体组成,变量名的主体应当使用“名词”或者“形容词+名词”,且首字母必须大写。 各种前缀字符可能组合使用,在这种情况下,各前缀顺序为: 变量作用域前缀、变量类型前缀。 5.4.12规则4-12 控件命名应采用完整的英文描述符命名,名字的前缀是控件类型名缩写。 说明: 控件 缩写 Label lbl TextBox txt CheckBox chk Button btn ListBox lst DropDownList ddlst 等等 5.4.13规则4-13 参数名应由前缀+变量名主体组成,变量名的主体应当使用“名词”或者“形容词+名词”,且首字母必须大写。 前缀为变量类型前缀。 5.4.14规则4-14 属性名用私有成员名称命名,但不带前缀,且首字母大写。 正例: publicclassHello { privatestringm_strName; publicstringName { get { returnm_strName; } } } 5.4.15规则4-15 方法名用大写字母开头的单词组合而成,且应当使用“动词”或者“动词+名词”(动宾词组)。 方法名力求清晰、明了,通过方法名就能够判断方法的主要功能。 方法名中不同意义字段之间不要用下划线连接,而要把每个字段的首字母大写以示区
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 软件工程 软件 代码 编程 规范