架构师职责-制定代码规范

说明：本规范分为不同的级别，默认级别为必须遵循级别，而(II)为建议级别，非强制执行。

1.格式与命名规范(Formating and Naming Conventions)

最重要:不用死记硬背，直接使用Eclipse的自动格式化功能。

换行:每行120字符以上--因为现在屏幕已大为宽广。

括号:if,for,while语句全部使用括号包围。

命名规则:

不允许使用汉语拼音命名

避免使用下划线(静态变量除外)

接口尽量采用"able", "ible", or "er"，如Runnable命名，尽量不采用首字母为I或加上IF后缀的命名方式，如IBookDao,BookDaoIF。(II)

2.注释规范(Document Convertions)

2.1 注释类型

JAVA DOC注释

/*** .... **/

失效代码注释

由/**... **/界定，标准的C-Style的注释。专用于注释已失效的代码。

代码细节注释

由//界定，专用于注释代码细节。

注意：即使有多行注释也仍然使用//，以便与用/**/注释的失效代码分开。

2.2 注释的格式

注释中的第一个句子要以（英文）句号、问号或者感叹号结束。Javadoc生成工具会将注释中的第一个句子放在方法汇总表和索引中。

为了在JavaDoc和IDE中能快速链接跳转到相关联的类与方法，尽量多的使用@see xxx.MyClass，@see xx.MyClass#find(String)。

Class必须以@author声明作者，体现代码责任。但不需要声明@version与@date，由版本管理系统保留此信息。(II)

标识(java keyword, class/method/field/argument名，Constants)在注释中第一次出现时以 {@linkxxx.Myclass}注解以便JavaDoc与IDE中可以链接。(II)

2.3 注释的内容

可精简的注释内容

注释中的每一个单词都要有其不可缺少的意义，注释里不写"@param name -名字"这样的废话。

如果该注释是废话，连同标签删掉它，而不是自动生成一堆空的标签，如空的@param name，空的@return。

推荐的注释内容

对于调用复杂的API尽量提供代码示例。(II)

对于已知的Bug需要声明，//TODO 或 //FIXME 声明:未做/有Bug的代码。(II)

Null规约: 如果方法允许Null作为参数，或者允许返回值为Null，必须在JavaDoc中说明。否则方法的调用者不允许使用Null作为参数，并认为返回值是Null Safe(不会返回NULL)。

3.编程规范(Programming Conventions)

3.1 基本规范

当API会面对不可知的调用者时，方法需要对输入参数进行校验，如不符合则抛出IllegalArgumentException，建议使用Spring的Assert系列函数。

因为System.out.println()，e.printStackTrace()仅把信息显示在控制台，因此不允许使用，必须使用logger打印并记录信息。

在数组中的元素(如String [1])，如果不再使用需要设为NULL，否则会内存泄漏。因此直接用Collections类而不要使用数组。

在不需要封闭修改的时候，尽量使用protected 而不是 private，方便子类重载。

变量，参数和返回值定义尽量基于接口而不是具体实现类，如Map map = new HashMap();

用double 而不是Float，因为float会容易出现小数点后N位的误差。

3.2 异常处理

重新抛出的异常必须保留原来的异常，即throw new NewException("message", e); 而不能写成throw new NewException("message")。

在所有异常被捕获且没有重新抛出的地方必须写日志。 --TODO

如果属于正常异常的空异常处理块必须注释说明原因，否则不允许空的catch块。

3.3 JDK5.0规范

重载方法必须使用@Override，可避免父类方法改变时导致重载函数失效。

不需要关心的warning信息用@SuppressWarnings("unused"), @SuppressWarnings("unchecked"), @SuppressWarnings("serial") 注释。