JAVA编码规范

JAVA编码规范

Java Coding Specification

目录

1 导言 5

1.1 目的 5

1.2 范围 5

1.3 角色和职责 5

1.4 术语定义 5

2 格式 6

2.1 .缩进 6

2.2间隔 7

2.3空行 8

2.4类成员的摆放顺序 8

2.5文件格式(File Format) 8

2.6行最大长度 9

2.7括号 9

3 命名规则 10

3.1 类和接口 10

3.2 包 10

3.3 get和set方法（属性的定义） 10

3.4 变量 11

3.4.1 普通变量： 11

3.4.2 常用对象变量 11

3.4.3 Static Final变量的命名 11

3.4.4 临时变量 12

4 注释 13

4.1 要求 13

4.2 JavaDoc说明 13

4.3 类 14

4.4 方法 15

4.5 代码的自我说明 16

5 编码 17

5.1 不要使用的结构 17

5.1.1 “do…while” 17

5.1.2 "return" (建议，尽量避免，也可以使用) 17

5.1.3 "continue" 17

5.1.4 "break" 17

5.2 不要混合使用递增运算符和递减运算符 17

5.3 变量初始化 18

5.4 魔鬼数字/字符 18

5.5 范围（scope） 18

 

1 导言

Java语言给了程序员充分的空间随意编写自己的代码，但也正是因为如此，一个程序员自己编写的代码往往不能被别的程序员很好的阅读和理解。

1.1 目的

本文档旨在提供一个编码的标准，以便所有Java代码在产生的一开始就能够在整个开发团队中保持一致，从而能够更好的阅读和修改代码。

1.2 范围

本文档适用于软通动力公司项目开发团队的所有成员，为了使项目的后期维护和修改变的容易，在每个项目开发中一定要遵守本文档中的规定术语定义

1.3 角色和职责

l 编码负责人：

本规范在具体项目中执行监督负责人。通过实施Source Review 制度，编程人员在完成自己的一个模块并提交测试前，由编码负责人进行Source Review，不符合本编程规约的程序一律打回，重新修改，即编码人你认为自己的程序没有任何的功能问题。

l 编码人员

本规范的遵守者。

1.4 术语定义

l Logger - 系统进行日志输出了类，为引用第三方（Apache Group）的输出类，具体用法见 Log输出规范的说明。

2 格 式

2.1 .缩进

所有的缩进皆为4个空格。对应的括号通常在同一列的位置上。例如：

void foo(){

    while ( bar > 0 ) {

        Logger.debug();

        bar-- ;

    }

 

    if ( oatmeal == tasty ) {

        Logger.debug("Oatmeal is good and good for you");

    }else if ( oatmeal == yak ) {

        Logger.debug("Oatmeal tastes like sawdust");

    }else{

        Logger.debug("tell me pleeze what iz dis 'oatmeal'");

    }

 

    switch( suckFactor ) {

        case 1:

            Logger.debug("This sucks");

            break;

        case 2:

            Logger.debug("This really sucks");

            break;       

        default:

            Logger.debug("whatever");

            break;

    }

}

 

1）．所有的缩进是由"Space(空格)键"形成的，而不是"Tab键"。

2）．所有的if、while和for语句中的"状态"内容必须用括号括起来，就算只有一个状态。

if ( superHero == theTick ) {

    Logger.debug("Spoon!");

}

2.2间隔

1）．所有的标识符都必须被空白字符包围。

    int theTick = 5 ;

    if ( theTick == 5 )  

这么做唯一可能成为麻烦的是复杂的布尔分析影响了清晰度，例：

    if ( ( hero == theTick ) && ( ( sidekick == arthur ) || ( sidekick == speak ) ) )

不如这样：    boolean isTickSidekick = ( ( sidekick == arthur ) || ( sidekick == speak ) );

if ( ( hero == theTick ) && isTickSidekick ) {

    …

}

2）．然而也有一些例外的情况，见下表：

 

例 外 情 况

原 由

正 确 示 例

错 误 示 例

方 法 名

习惯写法是在所有方法名之后直接跟上一个左括号

foo( i ) ;

start() ;

args [0] ;

tens [i] ;

数 组

习惯写法是在所有数组名之后直接跟上一个左方括号

args[0] ;

tens[ I ] ;

args [0] ;

tens [i] ;

自加、自减运算符

习惯写法是在所有一元运算符前面或后面直接加上操作数

++count ; i-- ;

++count ; i -- ;

造型运算符

习惯写法是所有造型都不加空格

(MyClass)v.get( 3 ) ;

(MyClass) v.get( 3 ) ;

( MyClass )v.get( 3 ) ;

2.3空行

应该时不时的在各方法之间加入一些空格行来分割大段的代码；

还应该在方法与方法之间加入一两行的空格行。

2.4类成员的摆放顺序

    class Order {

1. final attributes

2. attributes

3. constructors

4. methods

    }

必须保持private方法被放置在使用该方法的其他方法之上，而在构造器（constructor）之下，即使该构造器有可能调用这些private方法。

2.5文件格式(File Format)

"package"必须总保持第一个出现；

"import"其次；

再次，任何非javadoc的注释；

然后是javadoc类文件

最后便是类。

注意：一个文件(File)只能有一个类，内部类除外。

示例：

    package misc ;

 

    import java.io.* ;

    import java.net.* ;

 

    /** this class does cool stuff

      * @author Joe Programmer

      */

    class SpaceMonkey{

        ...

    }

2.6行最大长度

不要让一行代码的长度超过120个字符，最好是低于80个字符。如果代码开始向右延伸得很长，你就应该考虑把它分割成更多的方法。

2.7括号

使用括号的目的必须是在表达上不但能够标明优先顺序，而且有助于使表达更简单明了。另外，如果某一段代码有可能产生歧义，也需加括号。

 

 

 

 

3 命名规则

所有的标识符只能用字母（A-Z或a-z）和数字（0-9）。不能有货币符号或者其它非ASCII字符。Java中，除了包名，静态常量等特殊情况，大部分情况下标识符使用骆驼法则，即单词之间不使用特殊符号分割，而是通过首字母大写来分割。比如: SupplierName, addNewContract，而不是 supplier_name, add_new_contract。

 

3.1 类和接口

所有类和接口标识符将都使用混合"格"表示。每个名称中的每个单词首字母必须大写，同时这个名称的首字母也必须大写；其它的字母均小写，除了缩写词之外（它们必须全部大写）。

示例：

Customer

SalesOrder

TargetURL

URLTarget

 

3.2 方法名

首字母小写，如 addOrder()不要 AddOrder()；动词在前，如 addOrder()，不要orderAdd()；动词前缀往往表达特定的含义，如下表：

 

前缀名

意义

举例

create

创建

createOrder()

delete

删除

deleteOrder()

add

创建，暗示新创建的对象属于某个集合

addPaidOrder()

remove

删除

removeOrder()

init或则initialize

初始化，暗示会做些诸如获取资源等特殊动作

initializeObjectPool

destroy

销毁，暗示会做些诸如释放资源的特殊动作

destroyObjectPool

open

打开

openConnection()

close

关闭

closeConnection()<

read

读取

readUserName()

write

写入

writeUserName()

get

获得

getName()

set

设置

setName()

prepare

准备

prepareOrderList()

copy

复制

copyCustomerList()

modity

修改

modifyActualTotalAmount()

calculate

数值计算

calculateCommission()

do

执行某个过程或流程

doOrderCancelJob()

dispatch

判断程序流程转向

dispatchUserRequest()

start

开始

startOrderProcessing()

stop

结束

stopOrderProcessing()

send

发送某个消息或事件

sendOrderPaidMessage()

receive

接受消息或时间

receiveOrderPaidMessgae()

respond

响应用户动作

responseOrderListItemClicked()

find

查找对象

findNewSupplier()

update

更新对象

updateCommission()

 

3.3 包

所有包名只能用小写字母。尽量别使包名长度超过8个字符，应该避免使用多个词作为包名。

示例：

common

core

lang

3.4  get和set方法（属性的定义）

用于设置对象状态的方法必须在方法名前面加一个前缀set；用于检索一个布尔类型对象状态的方法必须在方法名前面加一个前缀is；而用于检索其它类型对象状态的方法则必须在方法名前面加上get。

示例：

setEnabled()

getName()

isEnabled()

3.5 变量

3.5.1 普通变量：

变量的命名应尽可能采用见名知义，基本命名规则如下：

变量名 = 变量前缀 + 变量含义

变量前缀遵循匈牙利命名规则，定义如下：

类型

前缀

short

s

int

n

char

ch

double

d

boolean

b

long

l

float

f

3.5.2 常用对象变量

类型

前缀

String

str

Vector

v

HashMap

hm

Hashtable

ht

Date

dt

Timestamp

ts

Collection

coll

Iterator

iter

List

lst

Object[]

aryObj

3.5.3 Static Final变量的命名 

Static Final 变量的名字应该都大写，每个单词之间用 ”_” 连接，并且指出完整含义。

3.5.4 临时变量

一般临时变量没有具体的意思，所以临时变量名为：

临时变量名 = 变量前缀 + （Temp或Tmp）；

其中有一些C语言延续下来的常见临时变量也可以接受：如i , j , k 一般用于表示一个临时整型变量。

 

 

4 注 释

大部分注释尽量用"//"；对于所有的javadoc的注释则用"/**  */"；而临时对代码块进行的注释尽量用"/*  */"。

4.1 要求

1、 程序中注释行应不少程序代码行的40%；

2、 类、方法、变量必须注释说明；

3、 注释内容应根据客户要求的语言进行，原则上，除常量、变量、变量类型等以外的说明尽可能采用中文注释；

4.2 JavaDoc说明

1）．JavaDoc注释将用于说明那些被其它类调用的类、属性和方法。这些注释必须出现在所要说明的各项之前。

2）．JavaDoc注释一般不会用于说明一些显而易见的方法，例如：

public static void main( String[ ] args ) 或public int getX( ) ；

3）．JavaDoc注释也不用于说明一些显而易见的参数，如：

public void setX( int newX ) ；

4）．诸如servlet和EJB等那些没有被其它类调用的类，也不必加JavaDoc注释。

把源码上交给整个团队之前，必须先经过JavaDoc处理，并全面检查处理结果，以确定说明文字确实可读而且清楚明白。

如果JavaDoc注释能够在一行内写下，则格式应该象下面这样：

   

/** Used to mark spots */

   int x ;

如果JavaDoc注释内容在一行内容纳不下，则其格式应该象下面这样：

   /** Set how much to grow when growth is needed. <p>

     * Smaller values will usually save memory, but frequent

     * reallocation may take a lot of time. <p>

     * @param HowMuch The number of extra ints to allocate when

     * memory reallocation is required.  Values must be greater than

     * zero. <p>

     */

    public void setExtra( int HowMuch )

{

……

}

注意：HTML标签<p>和<pre>的作用。<p>迫使一段代码进行分行，而<pre>…</pre>则让块文字以特定的字体表现出来并且保留所有的空格字符。

JavaDoc还允许使用其它的HTML标签，但是禁止使用header标签（如<h1>, <h2>等）你可以用<b>..</b>加黑文字，也可以用<I>..</I>使文字变为斜体。

注意：JavaDoc把每个JavaDoc注释的第一行划分出来以用于放置"内容表"。如何标识出这部分内容的结束边界线呢？JavaDoc定义这个标志为"一个句号后跟一个空格"。其它如"一个问号后跟一个空格"或"一个句号后跟一个<p>标签"都不是结束标志。如果在句号和<p>之间加一个空格，那么就有结束标志产生了。

 

4.3 类

类的JavaDoc说明文件必须包括以下内容：

（1）简要的提纲

（2）详细的描述

（3）使用该类的示例代码段

（4）用@author标签列出作者

注意：由于JavaDoc中一个"功能（feature）"限制，所有示例代码的每行前面必须加入一个星号，以便保存每行的缩进。例如：

 

    /** A vector class optimized for working with ints. <p>

      *  Like the Vector object, except rather than tracking a dynamic

      *  array of pointers to different objects, this is simply a

      *  dynamic array of ints.  The advantage is speed and memory

      *  savings.<p>

      *  Example:

      *  <pre>

      *        // report longest lines

      *        TextFileIn f = new TextFileIn("blather.txt");

      *        IntVector v = new IntVector();

      *        int longestLine = 0 ;

      *        boolean done = false ;

      *        while ( ! done )

  *        {

  *            String s = f.readLine();

      *            if ( s == null )

      *            {

  *                done = true ;

    *            }

      *            else

    *            {

    *                int sLength = s.length() ;

      *                if ( sLength > longestLine )

      *                {

    *                    longestLine = sLength ;

    *                }

    *                v.append( sLength );

    *            }

    *        }

      *        f.close();

      *        Logger.debug("The longest lines are on line numbers:");

      *        for ( int i = 0 ; i < v.length() ; i++ )

    *        {

      *            if ( v.get( i ) == longestLine )

      *            {

    *                Logger.debug( i );

    *            }

      *        }

      *  </pre>

      *  @author Adam Baum

      *  @author Justin Case

      */

     public class IntVector{

……

}

4.4 方法

方法的JavaDoc说明文档必须包含以下内容：

（1）简要的提纲；

（2）详细的描述（如果有必要在简要提纲内补充说明某些内容的话）；

（3）用JavaDoc的@param标签列出所有参数（如果有参数的话）；

（4）用JavaDoc的@return标签返回出方法的值列表（如果需要返回值的话）；

（5）用JavaDoc的@exception标签列出所有异常（exception）(如果有异常抛出的话)

示例：

    /** Get a copy of one int. <p>

      *  Retrieve an int relative to the index provided.<p>

      *  @param Index Which int (0 is the first int).<p>

      *  @return The retrieved int or zero if Index is outside of 0..length.<p>

      */

    public int get( int Index ) {}

4.5 代码的自我说明

"傻子写计算机识别的程序；程序员写人识别的程序。"

                --Martin Fowler, Refactoring：《提高代码的设计水平》

除了要尽力用文件说明程序的复杂算法，我们还必须尽量通过多用一些标识符来使程序的算法易读。这样有助于减少将来需要修改程序而不需修改说明文档而带来的麻烦。

    /** determine if the given year is a leap year. <p>

      *  The Gregorian calendar principal states that a leap year occurs

      *  every fourth year, except every 100 years, except every 400

      *  years. <p>

      *  @param year The year to be tested.  Make sure this is a four digit year!<p>

      *  @return true if "year" is a leap year. <p>

      */

      boolean isLeapYear( int year ) {

          boolean y4 = ( ( year % 4 ) == 0 ) ;

          boolean y100 = ( ( year % 100 ) == 0 ) ;

          boolean y400 = ( ( year % 400 ) == 0 ) ;

          return ( y400 || ( y4 && ! y100 ) );

      }

5 编 码

5.1 不要使用的结构

5.1.1  “do…while” 

不要用do…while循环,用while()循环

5.1.2 "return" (建议，尽量避免，也可以使用)

不要在一个方法的中间使用"return"，"return"只能出现在一个方法的末尾。

原因：在方法的中间使用"return"会给今后将方法拆分成几个更小的方法带来困难；而且它会迫使开发者不得不为该方法考虑多于一个的出口点。

5.1.3  "continue"

决不要用"continue"。

原因：continue会给将来把一个结构拆分成几个更小的结构或方法带来许多困难；而且她也会迫使开发者不得不为该结构考虑多于一个的结束点。

 

5.1.4 "break" 

"break"只能用于转换状态（switch statement）的控制。

原因：在转换状态控制之外的情况下使用break，会给将来把一个结构拆分成几个更小的结构或方法带来许多困难；而且她也会迫使开发者不得不为该结构考虑多于一个的结束点。

5.2 不要混合使用递增运算符和递减运算符

不要混合使用递增运算符和递减运算符，

原因：在方法调用或是数学运算中混合使用递增运算符（或递减运算符）会造成欠经验的程序员阅读的困难，他们也许会让你重写代码的。

所以，最好在递增运算符（或递减运算符）之间加上额外的行。

 

5.3 变量初始化

最好总是在每个变量出现的时候就马上进行初始化。

最好只在需要的时候再声明（declare）一个变量，不然的话会影响代码的执行效果。

示例：

     int secondWide = 12 ;

    int firstWide = doFoo( 20 , secondWide );

    doBar( firstWide , secondWide );

    int totalWide = firstWide + secondWide ;     //  很好!

5.4 魔鬼数字/字符

程序中应尽可能少使用数字/字符，尽可能定义静态变量来说明该数字/字符的含义，程序中需要赋值或比较时，使用前面定义的静态变量。

以下情况例外：

Ø 循环控制；

5.5 范围（scope）

原则上类的成员变量必须是总是private，尽量少用protected和public，但以下情况例外：

Ø 内部类的成员变量（可以为public）；

Ø 子类可继承的基类成员变量（可以为protected）；

Ø 并发控制中的信号变量（可以为public）。