JAVA编程规范

1．介绍

编码规范对于程序员而言尤为重要，有以下几个原因：

l         一个软件的生命周期中，80%的花费在于维护

l         几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护

l         编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码

l         如果你将源码作为产品发布，就需要确任它是否被很好的打包并且清晰无误，一如你已构建的其它任何产品

为了执行规范，每个软件开发人员必须一致遵守编码规范。

2．文件名

2.1           文件后缀

Java程序使用下列文件后缀：

 

文件类别	文件后缀
Java源文件	.java
Java字节码文件	.class
Jsp界面文件	.jsp
zk界面文件	.zul
Html界面文件	.html

2.2           常用文件名

 

文件名	用途
src	应用源代码存放文件夹
test	单元测试源代码存放文件夹
pages	存放界面文件
resources	存放资源文件
css	存放css文件
img	存放图片文件
js	存放javascript文件
i3-label_zh_CN.properties	ZK的国际化文件

 

3．文件组织

一个文件由被空行分割而成的段落以及标识每个段落的可选注释共同组成。超过2000行的程序难以阅读，应该尽量避免。

3.1           Java源文件

每个Java源文件都包含一个单一的公共类或接口。若私有类和接口与一个公共类相关联，可以将它们和公共类放入同一个源文件。公共类必须是这个文件中的第一个类或接口。

3.1.1     开头注释

/*

 * ISConsole Copyright 2008 COMPANY, Co.ltd .

 * All rights reserved.

 * Package:  com.service.impl

 * FileName: NetStationManagerServiceImpl.java

 */

 

3.1.2     包和引入语句

在多数Java源文件中，第一个非注释行是包语句。在它之后可以跟引入语句。例如：

package java.awt;

 

import java.awt.peer.CanvasPeer;

3.1.3     类和接口的注释

 

/**
      * @功能                       UI--用户登录
      * @author  创建人             Xxx

      * @date  创建日期       2007-03-03
      * @author  修改人               xxxx
      * @date  修改日期       2008-02-12
      * @author  修改说明    调整登录
      * @version 1.0
    */

注：修改说明这里可以只是做个简单的说明，具体情况可以看代码中的修改记录。

3.1.4     方法的注释

原则：以“/*”开始，“*/”结尾注释。写明程序作用，以及输入输出参数，和异常。例如：

/**

     * 根据业务命令，调用业务方法。

     * @param request HTTP请求

     * @param response HTTP应答

     * @param context HTTP上下文

     * @return boolean true：合法 false：失败

     * @throws EB_Exception处理异常

     */

    public boolean doGet(Request request, Response response, Context context)        throws EB_Exception {

        ……

        return true;

    }

3.1.5     属性的注释

原则：以“/*”开始，“*/”结尾注释。写明该属性的含义。例如：

    /**

     * 应用程序实例的类型

     */

    private String type;

 

3.1.6     方法内的注释

原则：语句末尾以“//”开始注释。例如：

    public static void logout()

    {

        Sessions.getCurrent().removeAttribute("userid"); //退出同时清除session中的UserID

        Sessions.getCurrent().removeAttribute("userip"); //退出同时清除session中的UserIP

        Sessions.getCurrent().removeAttribute("username"); //退出同时清除session中的UserName

    }

3.1.7     修改程序时必要的注释

u       增加代码

例如：

//add by chengdong 2008-03-10 begin

//增加登录校验功能

......

具体新增程序代码

......

//add by chengdong 2008-03-10 end

 

u       修改代码

原则上修改，删除的时候一定要保留原来的程序代码，不要直接修改或删除。可以用“/*  */”或者“//”进行注释后再做修改和删除。

例如：

//modify by chengdong 2008-03-10 begin

//修改登录校验功能

/*

......

Sessions.getCurrent().setAttribute("userid", id);

......

*/

......

具体新程序代码

......

//modify by chengdong 2008-03-10 end

u       删除代码

例如：

//del by chengdong 2008-03-10 begin

//删除原有获取数据集的方式

/*

public Vector getQueryData() throws EB_Exception

{

......

}

*/

//del by chengdong 2008-03-10 end

4．缩进排版

4个空格常被作为缩进排版的一个单位。缩进的确切解释并未详细指定(空格 vs. 制表符)。一个制表符等于8个空格(而非4个)。

4.1           行长度

尽量避免一行的长度超过80个字符，因为很多终端和工具不能很好处理之。

注意：用于文档中的例子应该使用更短的行长，长度一般不超过70个字符。

4.2           换行

当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之：

l         在一个逗号后面断开

l         在一个操作符前面断开(注：在一个操作符后面断开更好。)

l         宁可选择较高级别(higher-level)的断开，而非较低级别(lower-level)的断开

l         新的一行应该与上一行同一级别表达式的开头处对齐

l         如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进8个空格。

以下是断开方法调用的一些例子：

  someMethod(longExpression1, longExpression2, longExpression3,
                           longExpression4, longExpression5);

  var = someMethod1(longExpression1,
                            someMethod2(longExpression2,
                                                longExpression3));

以下是两个断开算术表达式的例子。前者更好，因为断开处位于括号表达式的外边，这是个较高级别的断开。

longName1 = longName2 * (longName3 + longName4 - longName5)
                              + 4 * longname6; //PREFFER
    longName1 = longName2 * (longName3 + longName4 - longName5) +
                              4 * longname6; //PREFFER (注：我的建议)
    longName1 = longName2 * (longName3 + longName4
                              - longName5) + 4 * longname6; //AVOID

以下是两个缩进方法声明的例子。前者是常规情形。后者若使用常规的缩进方式将会使第二行和第三行移得很靠右，所以代之以缩进8个空格

//CONVENTIONAL INDENTATION
    someMethod(int anArg, Object anotherArg, String yetAnotherArg,
                    Object andStillAnother) {
        ...
    }

//INDENT 8 SPACES TO AVOID VERY DEEP INDENTS
    private static synchronized horkingLongMethodName(int anArg,
          Object anotherArg, String yetAnotherArg,
          Object andStillAnother) {
        ...
    }

if语句的换行通常使用8个空格的规则，因为常规缩进(4个空格)会使语句体看起来比较费劲。比如：

// DON'T USE THIS INDENTATION
    if ((condition1 && condition2)
        || (condition3 && condition4) ||
        || !(condition5 && condition6)) { //BAD WRAPS
        doSomethingAboutIt(); //MAKE THIS LINE EASY TO MISS
   }
    // （注：比较好的用法）
    if ((condition1 && condition2) ||
        (condition3 && condition4) ||
        !(condition5 && condition6)) {
       doSomethingAboutIt();
    }

// USE THIS INDENTATION INSTEAD
   if ((condition1 && condition2)
        || (condition3 && condition4)
        || !(condition5 && condition6)) {
        doSomethingAboutIt();
    }

//OR USE THIS
   if ((condition1 && condition2) || (condition3 && condition4)
        || !(condition5 && condition6)) {
        doSomethingAboutIt();
    }

这里有三种可行的方法用于处理三元运算表达式：
   alpha = (aLongBooleanExpression) ? beta : gamma; // (注：我认为比较好的用法)

alpha = (aLongBooleanExpression) ? beta
                                : gamma;

alpha = (aLongBooleanExpression) // (注：我认为比较好的用法)
       ? beta
       : gamma;

5．注释

Java程序有两类注释：实现注释(implementation comments)和文档注释(document comments)。实现注释是那些在C++中见过的，使用/.../和//界定的注释。文档注释(被称为"doc comments")是Java独有的（注: C++中也使用），并由/*.../界定。文档注释可以通过javadoc工具转换成HTML文件。

实现注释用以注释代码或者实现细节。文档注释从实现自由(implementation-free)的角度描述代码的规范。它可以被那些手头没有源码的开发人员读懂。

注释应被用来给出代码的总括，并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和理解程序有关的信息。例如，相应的包如何被建立或位于哪个目录下之类的信息不应包括在注释中。

在注释里，对设计决策中重要的或者不是显而易见的地方进行说明是可以的，但应避免提供代码中己清晰表达出来的重复信息。多余的的注释很容易过时。通常应避免那些代码更新就可能过时的注释。

注意：频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候，考虑一下重写代码使其更清晰。

注释不应写在用星号或其他字符画出来的大框里。注释不应包括诸如制表符和回退符之类的特殊字符。

注：要求每个类、方法、变量都要有相应的注释，而且方法的注释必须把这个方法的逻辑思路讲清楚。

5.1           实现注释的格式

程序可以有4种实现注释的风格：块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line)。

5.1.1     块注释

块注释通常用于提供对文件，方法，数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方，比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。

块注释之首应该有一个空行，用于把块注释和代码分割开来，比如：

/*
     * Here is a block comment.
     */

块注释可以以/*-开头，这样indent(1)就可以将之识别为一个代码块的开始，而不会重排它。

/*-
     * Here is a block comment with some very special
     * formatting that I want indent(1) to ignore.
     *
     *    one
     *        two
     *            three
     */

注意：如果你不使用indent(1)，就不必在代码中使用/*-，或为他人可能对你的代码运行indent(1)作让步。

5.1.2     单行注释

短注释可以显示在一行内，并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完，就该采用块注释(参见"块注释")。单行注释之前应该有一个空行。以下是一个Java代码中单行注释的例子：

if (condition) {
    /* Handle the condition. */
     ...
}

5.1.3     尾端注释

极短的注释可以与它们所要描述的代码位于同一行，但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中，它们应该具有相同的缩进。

以下是一个Java代码中尾端注释的例子：

if (a == 2) {
        return TRUE; /* special case */
   }
   else {
        return isPrime(a); /* works only for odd a */
   }

5.1.4     行末注释

注释界定符"//"，可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本；然而，它可以用来注释掉连续多行的代码段。以下是所有三种风格的例子：