一、前言

这篇文档描述了Apache Portals工程源代码必须遵循的代码规范列表。默认的，大多数开源项目的代码都需要遵循现有编码标准.以下是Apache Portals 项目需要遵循的代码标准列表。没有在这里提及的地方，需要遵循官方的Sun Java Coding Conventions. 

二、示例说明

1.{}应当在一个新行中开始和结束（译者注：此处与SUN官方标准不一致）。 即使代码体中只有一行，也需要使用{}（译者注：此处与SUN官方标准一致）. 如:

if (foo){@b@    // code here@b@}@b@ @b@try{@b@    // code here@b@}catch (Exception bar){@b@    // code here@b@}finally{@b@    // code here@b@}@b@ @b@while (someCondition){@b@    // code here@b@}

2.虽然在(后面和)前面存在一个空格是被允许和被尊重的，但是更希望不包含空格. 以下两种方式都是可以的: 

if (foo)@b@@b@or@b@@b@if ( foo )

3.四个空格（而不是tabs）. 以前. 我们认同大多数开发者使用tab, 但是事实上，分布式的开发环境中使用tab使得代码不易读.

4.所有java源代码文件使用Unix换行符. 与平台相关的其他文件，应当使用平台规定的换行符. 

5.所有方法必须存在文件注释.如果您修改了类，方法，变量而没有文档注释您需要添加它. 这会改善整个工程. 怎样书写文档注释, 参见Sun's guidelines 

6.书写变量的文档注释时，尽量保持注释在一行内. 

/** Documentation of this variable */@b@private int myVariable;@b@@b@/**@b@ * If the documentation of the variable is enough to occupy multiple@b@ * lines, then this form of comment is also perfectly acceptable.@b@ */@b@private int myVariable;

7.Apache License 必须 放在每一个文件的最顶端. 

8.假如您捐献一个文件(代码或者文档), 将您自己加到最顶端的作者列表中. 您应当将自己加到作者列表的最后一位. Java文件的文档注释首选格式是: 

@author <a href="mailto:user@domain.com">John Doe</a>

9.所有 .java 文件应当有如下所示的 @version. 

@version $Id: code-standards.xml,v 1.1 2004/03/26 00:18:16 taylor Exp $

10.导入定义应当是类的全称. 

import java.util.ArrayList;@b@import java.util.Hashtable;@b@@b@import org.apache.foo.Bar;@b@import org.apache.bar.Foo;

而不是

import java.util.*;@b@import org.apache.foo.*;@b@import org.apache.bar.*;

11.导入语句应当以字母排序. 使用空行分隔不同的导入. 如, 您应当对java.util, java.swing, 等导入类进行分组，组之间以空行分开... 

12.IF或者WHILE语句的条件部分不应当使用==操作符测试TRUE和FALSE.

if (foo)@b@//而不是@b@if (foo==true)

13.在代码中总是使用短类名. 只有当全类名是必须时才使用全类名。如java.sql.Date 和 java.util.Date 在同一个类中使用时。其他情况下，您总是应当导入类并使用类的短名称 

try{@b@@b@}catch (IOException e){@b@@b@}@b@//而不是@b@try{@b@@b@}catch (java.io.IOException e){@b@@b@}

14.遍历时，避免在循环体外进行初始化，如. 

for (Iterator iter=getIterator(); iter.hasNext; ){@b@@b@}@b@@b@//而不是@b@@b@Iterator iter=getIterator();@b@@b@for (;iter.hasNext; ){@b@@b@}