当前位置: 首页 > 网站架构 > 正文

项目规范文档

1 星2 星3 星4 星5 星 (暂无评分)
Loading ... Loading ...
baidu_share
文章目录

在日常项目的维护中,良好的代码规范,命名标准规范,注释规范,日志标准规范,单元测试要求,SVN要求等方面做好标准规范,将会对项目开发,团队协作,后期维护起到很大作用。

代码风格

代码应该是简洁的,清晰的,可读性强的,高效的。模板保证新建的类和方法的注释风格一致,format格式一致(按120字符每行)。合理的缩进和空行,便于阅读代码。采用统一的代码格式生成xml。

命名标准规范

统一各种层次对象的命名,一方面是使得团队多人的代码更一致,更一方面更是我们自己概念理解的统一。

项目
统一使用xx-xxx方式命名project,比如xx-web,xx-biz等等。

包、类
包名必须小写,尽量一个单词或缩写。
包名应该和所在项目名一致,与包下的类的作用一致。
实现类所在的包应该是接口或抽象类的包名后缀.impl。
类名的每个单词首字母必须大写。
类名必须能直接表达本类的作用。
类名的后缀必须表达出其所在分层,比如Controoler,VO,Manager,Service,DAO等等。

方法
方法名称首字母必须小写,后续每个单词首字母大小。
方法名必须能直接表达方法体的作用。
参数名称必须是有意义的。
增删改查的方法使用create, delete, update, find开头。

局部变量
局部变量名称必须是有意义的,禁止使用user1,user2,user3,a,b,c命名。

常量
静态常量需要加上final。
公用的常量必须放在常量类中
非公用的常量可以放置在使用的类中,声明为private
可以枚举的常量集合必须使用常量或枚举类
常量名称必须是有意义的
常量必须全部大写,并使用下划线连接不同的单词
使用很少的字面量,在不影响阅读的情况下可以不使用常量声明,直接写在代码中。

配置文件
spring相关的配置文件,按层次或功能划分不同的配置文件
spring所有的bean,一般按照类名或接口名首字母小写命名
spring配置文件默认使用byname的autowire
sqlmap必须使用xxxx-sqlmap结尾

VM文件
文件名必须与内容在意义上一致。
文件名首字母小写,后续单词首字母大写。
vm文件中的变量引用需要注意使用!判断空

注释规范

如果说代码本身说明了在做什么,注释则是说明了为什么要这么做。复杂的代码没有注释,过几天你自己都看不懂了。

接口、类和public的方法必须要有注释,请参考风格模板,或者eclipse里在方法和类上shift、alt+J
待定的功能、review的问题、修复的bug,请使用TODO,REVIEW,FIXME标记。

bug修复,问题排查时修改的关键代码,请加上注释,说明修改人,修改时间,问题分析和采取的措施,如果说明较多在wiki上,请加上链接。

日志标准规范

日志是用来排查问题的,你今天写什么注定你以后用什么。

所有写操作必须有日志。
所有日志必须有唯一标识(比如update一条数据,必须记录id)。
必须说清楚本操作是做什么的,影响了什么,结果如何。
所有与第三方交互数据必须输出原始报文(比如xml或soap)。
日志必须使用enabled判断:log.isDebugEnabled(){ log.debug(…); }

单元测试要求

单元测试的目的是持续的保证代码方法层次的逻辑是对的,一直都是对的,改了也是改对了的。
最小粒度方法级的逻辑测试。
覆盖所有逻辑分支判断和边界条件。
不依赖具体的某些绝对条件,比如写死的日期。
不能catch异常不处理。
test case不得在运行时有依赖关系。
test case的包名类名与被测类保持一致。
test case的方法建议一般使用中文。
能mock的对象尽量mock,比如对外部的依赖,本test case不关注的manager
核心模块如biz、dal、core,要求必须70%以上。
其他模块如web等,建议30%以上。

SVN要求

svn是可靠的,当然前提是使用svn的人必须是可靠的。
提交时必须输入说明修改目的的备注,比如修改日期格式化错误问题,解决bug id:123456
分支名称必须带日期版本号加上分支说明,比如廉航的分支:v051216_20120308_Lianhang

其他要求

整个项目使用UTF-8编码。设计文档评审前必须发出并收集反馈意见,评审需要针对意见。模块代码完成和大范围修改(非小bug fix),必须code review。

本文固定链接: http://www.chepoo.com/project-specification-documents.html | IT技术精华网

【上一篇】
【下一篇】

项目规范文档:等您坐沙发呢!

发表评论