软件编码规范.doc

软件编码规范文档编号版本号分册名称软件编码规范第册共册总页数正文附录编制审批生效日期第页共页修改记录版本号变更控制报告编号更改条款及内容更改人审批人更改日期初稿第页共页目录第页共页第章命名规范和和两者都是比较流行的命名法将描述变量或方法的所有单词小写直接连接起来第一个单词的首字母小写其后单词的首字母大写的写法叫做骆驼拼写法如变量名方法名所有单词首字母都大写的写法叫做帕斯卡拼写法如变量名方法名一言概之类接口的命名用方法变量的命名用而包的命名全部小写常量的命名全部大写原则望文生义如用户角色密码等可用但对于一些复杂的专业名词则不建议用英文方式命名而应该采用拼音首字母的方式如地方一级产业商品课税类型成品油改革上划中央的城建税和教育费附加费适用于这种特殊情况包命名包属于一种特殊情况它们全都是小写字母即便中间的单词亦是如此包名称分为三部分公司域名反转系统名称分区名称其中模块名称是可选的根据实际情况而定例如中标数据的权限中心系统英文名称是有一个模块叫后台管理英文名称是它里面的接口或类的包名为其实在分层架构系统中分层名往往是包名的一部分一般置于分区名前例如有一个业务逻辑层即上面的包名应该为这属于系统设计范畴不在命名规范范畴内讨论模块名称必须用英文类命名名词采用拼写法尽可能采用简短且意义明确的单词避免使用缩第页共页写除非该缩写因长期使用已被公认例如是表明是用户数据访问对象如果某个类是某张表的映射类则类的名称与表名一致例如用户表名为是前缀表明这是一张表详细规范见数据库设计规范则其映射类名为接口命名类名加前缀例如字段命名采用拼写法例如如果某个类是某张表的映射类则类的属性字段名与表的字段名一致例如表有字段则在映射类中对应的字段为方法命名动词名词其中名词是可选的采用拼写法动词要生动贴切例如类的获取方法被访问字段例如有一个字段为则其获取方法为类的设置方法被访问字段例如有一个字段为则其设置方法为第页共页类的布尔型判断方法使用作前缀例如或者使用具有逻辑意义的单词例如或涉及到数据的增删改查的方法统一用以下几个字母打头例如如果是在同一个实体访问类里例如由于上下文就是则对应的方法名为如果确定查询条件的如根据来查询则为如根据用户名和密码来查询则为变量命名采用拼写法由于一般都具有语法提示功能并且的语法很严谨为了简洁不用加数据类型作为变量的前缀要望文生义变量的命名要生动贴切一般不建议缩写我们从来不害怕长的变量命名却担心看不懂的命名例如有一个记录产品类型数量的变量我们一眼就看出它是记录产品类型数量的而这是糟糕的命名它是的简写但是其他人或者我们在长时间以后还能知道它是做什么的吗也许我们不得不查阅相关文档或跟踪代码前后文以明白其意义在小的语句块里即用即弃的临时变量可以缩写或者单字母例如第页共页数组命名数据类型变量名例如而不是常量命名常量的命名有别于和全部使用大写字母单词之间以下划线相连例如避免使用不易理解的数字用有意义的标识来替代尽量使用枚举和常量来代替例如不推荐下面写法而推荐下面写法此写法不单易懂而且统一因为可能在程序的多个文件多个地方使用到文件命名文件和类名一致例如第页共页文件规范动词名词其中名词是可选的采用拼写法动词要生动贴切建议与中的方法名一致常用与类的方法名一样文件也有常用的命名一般与对应的类方法名一致例如查询页面或创建页面或修改页面或明细页面或第章书写规范排版每低一级使用一个缩进左大括号和右大括号之后换行并保持缩进对于等语句无论是否有语句体还是只有一条语句必须带有一对大括号一条语句占一行排版如下第页共页建议句块使用格式而不建议无论使用哪一种都只能使用一种而不能两种都使用空行在下列位置添加一个空行声明之后声明之后方法之间句块之间多行注释之前类之间第页共页接口之间空格页在下列位置添加一个空格逗号或分号的后面双目操作符等的前后下面情况不加空格单目操作符等前后方法名与其参数的左右括号之间引入页最好不用这种方式应该使用完整的包名和类名标准的包名要在本地的包名之前而且按照字母顺序排列次序先是字段再是构造函数后是方法对多态方法参数少的在前参数多的在后先是再是后是对于同一个字段先是后是类入口方法置于最后换行在类中或在的脚本中每一行的代码控制在个字符包括该行前面的空格以内对于超出个字符的可考虑换行新的行在第一行的基础上缩进一个或两个如果是由连接的诸如链式操作的语句则从处开始换行每一个为一行例如如下代码是的语法仅用作链式操作语句断行的例子http12025210358090downloadattachments884909worddavc6fcd89febd07fa2e86b95e781828211pngversion1ampmodificationDate1465112100000ampapiv2第页共页不同类型的代码放在不同的行同类型的代码放在同一行例如下面代码把放在同一行http12025210358090downloadattachments884909worddav12cf2edf66394f2f9c840300678c3a4bpngversion1ampmodificationDate1465112100000ampapiv2参数过多的可考虑在每一个参数前换行即每一个参数为一行例如http12025210358090downloadattachments884909worddav176dae3de13353639fb31d1bed149b86pngversion1ampmodificationDate1465112100000ampapiv2第章注释规范概述项目的技术文档最终将由命令从源文件的注释中提取因此注释的格式将以的格式为基础具体细节请参阅的说明文档有三种注释单行注释http12025210358090downloadattachments884911worddav9f44f3142f7ff9ffee8195f004544103pngversion1ampmodificationDate1465112100000ampapiv2多行注释http12025210358090downloadattachments884911worddavca72471c36768cd550fbd2f89648bd4bpngversion1ampmodificationDate1465112100000ampapiv2文档注释第页共页http12025210358090downloadattachments884911worddava331eb4d2a98c46d582a0a6a6e150048pngversion1ampmodificationDate1465112100000ampapiv2文档注释只描述紧跟其后的类属性或方法紧跟两字很重要内容可以含有标签如等原则一语中的注释要中肯不能词不达意或者挂羊头卖狗肉简洁注释不是越多越好如果程序简单到不用注释而读者也能容易读得懂那就是至高境界文件注释类的简述或详述接口的简述或详述字段成员变量说明对于其和方法在字段已注释的情况下可以不加注释方法说明过长的方法按功能实现逻辑进行分段概括说明不易理解的分支所满足的条件复杂的循环出口条件过长的条件循环句块在结束的附近进行简短的起始描述比如废弃的代码类注释采用文档注释格式如下第页共页http12025210358090downloadattachments884914worddav9f4f14157e5163216e5f49968b912f4epngversion1ampmodificationDate1465112101000ampapiv2这些标签的位置不能乱多个作者则使用多个标签多个参考目标则使用多个标签类注释中的标签一般标识的是类名如果当前类文件中的包含了的类可以只写出类名如如果没有包含则需要写出全类名如多个的次序第页共页接口注释同类注释字段注释采用文档注释格式如下http12025210358090downloadattachments884916worddava7308afd5d8c0691baa799a1e1482cd2pngversion1ampmodificationDate1465112101000ampapiv2方法注释采用文档注释格式如下http12025210358090downloadattachments884917worddav1ef73b6daacb112a7a8d847aa04e9966pngversion1ampmodificationDate1465112101000ampapiv2这些标签的位置不能乱行注释采用单行注释注释第页共页把注释内容置于需要被注释的代码的前面一行也可以同一行块注释采用多行注释或单行注释注释或注释废弃代码注释采用多行注释废弃代码在不确定可不可以删除的情况下可以用注释掉并说明注释掉的原因作者和时间格式如原因作者时间废弃代码注释哪些部分类的简述或详述接口的简述或详述第页共页字段成员变量说明对于其和方法在字段已注释的情况下可以不加注释方法说明过长的方法按功能实现逻辑进行分段概括说明不易理解的分支所满足的条件复杂的循环出口条件过长的条件循环句块在结束的附近进行简短的起始描述比如废弃的代码第章经验规范优先级尽可能利用括号表示表达式之间的优先级即使它看起来是理所当然的例如不建议建议三目表达式建议使用三目建议不建议第页共页如果三元表达式的判断条件是一段子语句则使用括号例如其它避免多个变量同时赋值例如避免不要使用内置赋值语句例如