[转]xx项目代码规范与项目质量

 

从以往各种的经验来看，一个优秀的产品或项目，经过千锤百炼，成为一个内涵丰富的宝藏：文档、代码、设计、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

 

 

参考列表

xxxxx

 

转处：kimmking