java编码规范

Juey 2013-06-11




   * 1 规范的规范
   * 2 代码编码
   * 3 代码布局
   * 4 Java包命名
   * 5 webapps应用目录命名
   * 6 Java代码命名
   * 7 Java源文件编写约定
   *
      * 7.1 内容元素顺序
      * 7.2 注释
      *
         * 7.2.1 注释的格式
   * 8 其他规范
   * 9 自动代码检查

规范的规范

  1. 本规范的每一条目必须无二义性,并且可执行。否则作废
  2. 本规范的条目分为两个级别:
规则 R- 要求所有项目中的所有成员遵守
建议 S- 建议所有项目中的所有成员遵守
  3. 本规范所有的“规则”条目必须被遵守

代码编码
完全采用UTF-8编码
代码布局
R-完全采用maven的默认布局。
src main 源码目录   main/java java源文件   main/resources 其他资源,如checkstyle脚本   main/webapp Web应用目录   main/config 配置文件模版   main/filters 不同profile下的配置   test 测试目录,结构与主源码目录相同   test/java/unit 单元测试   test/java/intergration 集成测试   test/functional 功能测试   test/data 测试数据生成器 target   maven编译目录
Java包命名
R-采用按层次分包的策略,层次内按功能划分。
com.zhimei.子项目名       web.controller 控制器controller   web.filter 过滤器filter   service 业务逻辑接口   service.impl 业务逻辑实现   job quartz等job启动地儿   log 特殊log记录,log分析   stat 数据库统计、网站排名   pojo 实体bean,一般是对应的数据字典   pojo.vo vo对象,一般是是对pojo的再分装   dao 数据操作DAO   dao.jdbc jdbc的数据操作   dao.mongo mongodb的数据操作   const 所有常量   util 常用工具类,应该集成到jmind

   * R-包名必须全部小写,2个以内单词。
   * S-最好为1个单数名词

webapps应用目录命名
R-webapps应用目录
webapp       tmp 临时文件   images 图片   scripts 脚本   css 样式   WEB-INF/spring spring配置文件   WEB-INF/jsp jsp   WEB-INF/taglib jsp标签库
Java代码命名

   * S-类和接口最好为名词
   * R-命名类和接口时,需要将所有单词的首字母大写
   * R-严格遵守java命名约定,命名尽量不超过15个字符
   * R-不允许使用汉语拼音命名
   * R-避免使用下划线(静态变量除外),静态变量必须全大写
   * R-抽象类必须使用 Abstract 作为类名的前缀
   * R-接口的命名不采用首字母为 I 或加上 IF 后缀的命名方式 。例如:IBookDao、BookDaoIF 等
   * R-遇到缩写如XML、URL时,仅首字母大写,即loadXmlDocument()而不是loadXMLDocument()
   * R-局部变量及输入参数不要与类成员变量同名(get/set方法与构造函数除外)
pojo 参照业务数据字典命名 dao 根据相应资源命名,并以Dao结尾 web.controller 根据相应资源命名,并以Controller结尾 web.filter 根据相应资源命名,并以Filter结尾 service 接口根据相应逻辑命名,并以Service结尾 service.impl 实现根据相应逻辑命名,并以ServiceImpl结尾 job 根据相应逻辑命名,并以Job结尾 const 根据相应逻辑命名,并以Const开头
   * S-数据库Column命名尽量考虑可直接作为对象的属性名,如列user_name将被映射为属性userName.
   * S-成员变量最好为单数名词
   * S-如果是集合或数组,用复数名词
Map pets, 比 Map petMap 要好
   * R-任何变量不要用一个字母,尤其是 i,你可以用 index 或者 cursor 来代替。除非循环变量。

Java源文件编写约定内容元素顺序

   * S-按照eclipse默认members sort order
静态变量 Static Fields 静态初始化 Static Initializers 静态方法 Static Methods 成员变量 Fields 初始化 Initializers 构造器 Constructors 成员方法 Methods 重载自Object的方法 如toString(), hashCode() 和main方法 类型(内部类) Types(Inner Classes)


   * R-修饰符应该按照如下顺序排列:public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp
   * R-能private就不要 protected,尽量不要public,最好不要 default

注释
Java程序有两类注释:实现注释(implementation comments)和文档注释(document comments)。Ctrl + /
只是用//不使用/* */
文档注释(被称为"doc comments")是Java独有的,并由/*.../界定。文档注释可以通过javadoc工具转换成HTML文件。

   * R-注释必须和代码保持同步

注释的格式

   * R-注释中的第一个句子要以(英文)句号、问号或者感叹号结束。Javadoc生成工具会将注释中的第一个句子放在方法汇总表和索引中。
   * S-为了在JavaDoc和IDE中能快速链接跳转到相关联的类与方法,尽量多的使用@see xxx.MyClass,@see xx.MyClass#find(String)。
   * S-如果注释中有超过一个段落,用<br>或者<p>分隔。
   * S-如果注释中有多个章节,用<h2>标签声明每个章节的标题
   * S-示例代码以<pre></pre>包裹。
   * S-标识(java keyword, class/method/field/argument名,Constants) 以<code></code>包裹。
   * S-标识在第一次出现时以{@linkxxx.Myclass}注解以便JavaDoc与IDE中可以链接。
   * S-简单的 get/set 方法可以省略注释。
   * S-继承的方法可以省略注释,但是被继承方法必须有注释。继承方法可以使用{@inheritDoc}引用被覆写方法的注释
   * R-函数内部不要写 JAVA DOC,没意义
   * R-代码质量不好但能正常运行,或者还没有实现的代码用//TODO:声明
   * R-存在错误隐患的代码用//FIXME:声明
   * R-在 if ... else .. 分支上做注释格式应该如下:




// comments for case A
if(xxxx){
        //TODO you code here
}
/*
 * Multipline comments for case B
 */
else if(xxxxx){
        //TODO you code here
}
// comments for default case
else{
        //TODO you code here
}
   * S-在本函数中抛出的unchecked exception尽量用@throws说明
   * S-对于调用复杂的API尽量提供代码示例
   * R-public、protected方法及变量必须写注释

其他规范

   * R-你的每一次提交,必须都是本地测试通过的
   * S-你的每一次提交,最好都是通过 JUnit 测试的
   * R-隐藏工具类的构造器,确保只有static方法和变量的类不能被构造实例
   * R-变量,参数和返回值定义尽量基于接口而不是具体实现类,如Map map = new HashMap()
   * R-提交代码中不能使用System.out.println(),e.printStackTrace(),必须使用logger打印信息。
   * R-重新抛出的异常必须保留原来的异常,即throw new NewException("message", e); 而不能写成throw new NewException("message")
   * R-在所有异常被捕获且没有重新抛出的地方必须写日志
   * R-重载方法必须使用@Override,可避免父类方法改变时导致重载函数失效。
   * S-不需要关心的warning信息用@SuppressWarnings("unused"), @SuppressWarnings("unchecked"), @SuppressWarnings("serial") 注释
   * S-用double 而不是float,因为float会容易出现小数点后N位的误差。能用int就不用double。
   * R-删掉一段代码的贡献,比增加一段代码的贡献要大
   * R-避免过度设计,先让代码能工作,然后重构成为优美的代码
   * R-每个方法不能超过50行有效代码。
   * R-每个类不能超过1000行有效代码。

自动代码检查
使用Eclipse的代码校验功能已经排除了很多问题formatter cleanup。
再配合使用Checkstyle,PMD-CPD,FindBugs三重检查,总共五层的校验涵盖了Java编码大部分的Guide Line

相关推荐

opspider / 0评论 2012-09-25