从以往各种的经验来看,一个优秀的产品或项目,经过千锤百炼,成为一个内涵丰富的宝藏:文档、代码、设计、bug的fix和各种思想的火花,都沉淀下来,变成了很多人长期的资产和营养。在这个过程中,项目的质量是长期稳定的。但是一个一般的项目,由于各种因素,开始就质量一般,后来又各种曲折,最终项目质量会从开始的一般水平,很快的下降,收敛到一个非常低得水准。在这个过程中,文档和设计开始残缺,代码开始腐朽,散发着我们常说的bad smell的味道。那么如何防止这个变坏的过程呢?一是项目一开始就要按照一个简单高效的方式实施一些规范:代码风格、命名、注释等等,约束概念和形式上的一致性;二是制定较高的质量目标:unit test和code/sql/document review等等,提高项目质量;三是持续的执行。
代码风格
-- 亲,一个不合适的ctrl+f会变成merge代码的噩梦,请每次格式化的时候,考虑下你用的是不是跟大家一致的模板。
-- 代码应该是简洁的,清晰的,可读性强的,高效的
模板保证新建的类和方法的注释风格一致,format格式一致(按120字符每行)。
合理的缩进和空行,便于阅读代码。
提供格式模板,请在eclipse中使用:
详见上面链接wiki文档的附件,其中codetemplate.xml用于eclipse的java-code style-code template,eclipsetemplate.xml用于java-code style-Formatter。
命名标准规范
-- 统一各种层次对象的命名,一方面是使得团队多人的代码更一致,更一方面更是我们自己概念理解的统一。
项目
统一使用ieo-xxx方式命名project,比如ieo-web,ieo-biz,ieo-common等等。
包、类
包名必须小写,尽量一个单词或缩写。
包名应该和所在项目名一致,与包下的类的作用一致。
实现类所在的包应该是接口或抽象类的包名后缀.impl。
类名的每个单词首字母必须大写。
类名必须能直接表达本类的作用。
类名的后缀必须表达出其所在分层,比如Screen,AO,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文件中的变量引用需要注意使用!判断空。
名词参照表
对于行业相关术语的和常用命名的前缀,请在这里查询,如果找不到请添加到这里并周知大家:
xxxxxxx
注释规范
-- 如果说代码本身说明了在做什么,注释则是说明了为什么要这么做。复杂的代码没有注释,过几天你自己都看不懂了。
接口、类和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
其他要求
整个项目使用GBK编码
设计文档评审前必须发出并收集反馈意见,评审需要针对意见
模块代码完成和大范围修改(非小bug fix),必须code review