1.2 相關知識

Java常見編碼規范包括：文件后綴名、源文件樣式約定、注釋規范、命名規范等。定義此種規范的目的在于讓項目中所有的文檔格式的統一，增加可讀性。

1.2.1 文件后綴名

這部分列出了常用的文件類別及其后綴名，如表1-1所示。

表1-1　Java程序使用的文件后綴名

其中兩者最本質的區別在于，.java文件是供虛擬機運行時執行的文件，而.class文件可以讓你在任何一臺安裝了Java虛擬機的機器上運行。

1.2.2 源文件樣式約定

Java源文件必須按順序由以下3部分組成。

? 版權信息。

? 包和引入語句。

? 類和接口聲明。

1. 版權信息

版權和版本信息必須在Java文件的開頭，其他不需要出現在Javadoc的信息也可以包含在這里。

例如：

/ ** 
*Title:  確定鼠標指針位置類 
* Description: 確定鼠標指針當前在哪個作業欄位中并返回作業號 
* @Copyright: Copyright (c) 2017 
* @Company: daiinfo 
* @author: daiyuanquan 
* @version: 1.0                     
* / 

2. 包和引入語句

package行要在import行之前，import中標準的包名要在本地的包名之前，而且按照字母順序排列。如果import行中包含了同一個包中的不同子目錄，則應該用*來處理。

例如：

package com.hbliti.net.stats;  
import java.io.*;
import java.util.Observable;
import com.hbliti.util.Application;

3. 類和接口聲明

每個Java源文件都包含一個單一的公共類或接口。類或接口的各部分代碼順序如下:

（1）常量聲明；

（2）靜態變量聲明；

（3）成員變量聲明；

（4）構造函數部分；

（5）Finalize部分；

（6）成員方法部分；

（7）靜態方法部分。

表1-2描述了類和接口聲明的各個部分以及它們出現的先后次序。

表1-2　類和接口聲明的各個部分順序

（1）類/接口文檔注釋舉例如下所示。

/ **    
* Title: 文件名稱    
* Description: 類內容的簡介   
*更新記錄：    
* 格式:[更新日期][修改的版本][操作人]內容  
 * [2017-06-28][1.0][戴遠泉]完善create方法。<br>
*   
* Copyright: Copyright (c) 2017   
* Company:   Daiinfo Co. Ltd.   
* @version: 1.1  
* / 

（2）類或接口的聲明舉例如下所示。

public class CounterSet extends Observable implements Cloneable｛  
… 
… 
 } 

（3）類/接口實現的注釋。該注釋應包含任何有關整個類或接口的信息，而這些信息又不適合作為類/接口文檔注釋。舉例如下所示。

/ ** 
* @see UserDao#save(User) 
* / 
public void save(User user) throws Exception{ 
  
} 

（4）類的（靜態）變量。靜態變量是基本數據類型，這種情況下在類的外部不必創建該類的實例就可以直接使用。舉例如下所示。

class Value{ 
  static int c=0; 
  Value(){ 
    c=15; 
  } 
  Value(int i){ 
    c=i; 
  } 
  static void inc(){ 
    c++; 
  } 
} 
class Count{ 
  public static void prt(String s){ 
    System.out.println(s); 
  } 
    Value v=new Value(10); 
    static Value v1,v2; 
    static{ 
      prt("v1.c="+v1.c+"  v2.c="+v2.c); 
      v1=new Value(27); 
      prt("v1.c="+v1.c+"  v2.c="+v2.c); 
      v2=new Value(15); 
      prt("v1.c="+v1.c+"  v2.c="+v2.c); 
    } 
  public static void main(String[] args){ 
    Count ct=new Count(); 
    prt("ct.c="+ct.v.c); 
    prt("v1.c="+v1.c+"  v2.c="+v2.c); 
    v1.inc(); 
    prt("v1.c="+v1.c+"  v2.c="+v2.c); 
    prt("ct.c="+ct.v.c); 
  } 
} 

（5）成員變量舉例如下所示。

/ **    
* Packet counters   
* /   
protected int[] packets; 

public的成員變量必須生成文檔（JavaDoc）。protected、private和package定義的成員變量如果名字含義明確的話，可以沒有注釋。

（6）構造函數舉例如下所示。

public CounterSet(){   
  this.size = 100;  
}   
public CounterSet(int size){  
  this.size = size; 
} 

應該用遞增的方式寫（比如參數多的寫在后面）。

（7）成員方法舉例如下所示。

/ **  
* param r1 - ??   
* param r2 - ??   
* param r3
* param r4
* /  
protected final void setArray(int[] r1, int[] r2, int[] r3, int[] r4)   throws IllegalArgumentException{   
   // Ensure the arrays are of equal size  
??  
} 

（8）toString方法舉例如下所示。一般情況下，每一個類都應該定義toString方法。

public String toString() {     
…  
} 

1.2.3 注釋規范

代碼注釋是架起程序設計者與程序閱讀者之間的通信橋梁，可以最大限度地提高團隊開發合作效率，也是提高程序代碼可維護性的重要環節之一。所以我們不是為寫注釋而寫注釋。

1. 注釋編寫的原則

（1）注釋形式統一。在整個應用程序中，使用具有一致的標點和結構的樣式來構造注釋。如果在其他項目中發現它們的注釋規范與這份文檔不同，按照這份規范寫代碼，不要試圖在既成的規范系統中引入新的規范。

（2）注釋內容準確簡潔。內容要簡單、明了、含義準確，防止注釋的多義性，錯誤的注釋不但無益反而有害。

2. 注釋類型的基本劃分

（1）基本注釋必須要添加，包括以下幾種。

? 類（接口）的注釋；

? 構造函數的注釋；

? 方法的注釋；

? 全局變量的注釋；

? 字段/屬性的注釋；

簡單的代碼做簡單注釋，注釋內容不大于10個字即可，另外，持久化對象或VO對象的getter、setter方法不需加注釋。

（2）特殊必加的注釋包括以下幾種。

? 典型算法必須有注釋；

? 在代碼不明晰處必須有注釋；

? 在代碼修改處加上修改標識的注釋；

? 在循環和邏輯分支組成的代碼中加注釋；

? 為他人提供的接口必須加詳細注釋。

具體的注釋格式自行定義，要求注釋內容準確簡潔。

3. 注釋的格式

（1）單行（single-line）注釋格式為“//……”。

（2）塊（block）注釋格式為“/ *……* /”。

（3）文檔注釋格式為“/ **……* /”。

（4）Javadoc注釋標簽語法如下：

? @author　對類的說明，標明開發該類模塊的作者；

? @version　對類的說明，標明該類模塊的版本；

? @see　對類、屬性、方法的說明，參考轉向，也就是相關主題；

? @param　對方法的說明，對方法中某參數的說明；

? @return　對方法的說明，對方法返回值的說明；

? @exception　對方法的說明，對方法可能拋出的異常進行說明。

例如：構造方法注釋如下。

public class OkButton extends Button { 
  / ** 
   * 構造方法的描述 
   * @param name 
   *  按鈕上顯示的文字 
   * / 
  public Test(String name){ 
     …… 
  } 
} 

1.2.4 命名規范

命名指系統中對包名、目錄（類名）、方法、常量、變量等標識符的命名。標識符的命名力求做到統一、達意、簡潔，遵循駝峰法則。

統一是指對于同一個概念，在程序中用同一種表示方法。例如對于供應商，既可以用supplier，也可以用provider，但是我們只能選定一個使用，至少在一個Java項目中保持統一。

達意是指標識符能準確地表達出它所代表的意義，如newSupplier，OrderPaymentGateway Service等；而supplier1、service2、idtts等則不是好的命名方式。

簡潔是指，在統一和達意的前提下，用盡量少的標識符。如果不能達意，寧愿不要太簡潔。例如，theOrderNameOfTheTargetSupplierWhichIsTransfered太長，transferedTargetSupplierOrderName則較好，但是transTgtSplOrdNm就不好了。省略元音的縮寫方式不要使用，我們的英語往往還沒有好到看得懂奇怪的縮寫。

用駝峰法則是指單詞之間不使用特殊符號分割，而是通過首字母大寫來分割。例如推薦用SupplierName，addNewContract，而不是supplier_name，add_new_contract。

1. 包名命名規范

包名按如下規則組成。

[基本包].[項目名].[模塊名].[子模塊名]……

例如：com.czpost.eims

com.hepost.eims.until...

不得將類直接定義在基本包下，所有項目中的類、接口等都應當定義在各自的項目和模塊包中。

2. 類名命名規范

（1）首字母大寫。

類名要首字母大寫，例如可以用SupplierService，PaymentOrderAction；不要用supplierService，paymentOrderAction。

（2）添加有含義的后綴。

類名往往用不同的后綴表達額外的意思，如表1-3所示。

表1-3　類名命名后綴名含義

3. 方法名命名規范

方法的命名規范有：首字母小寫，如使用addOrder()，不要用AddOrder()；動詞在前，如使用addOrder()，不要用orderAdd()。

動詞前綴往往表達特定的含義，如表1-4所示。

表1-4　方法名命名后綴名含義

4. 常量命名規范

常量必須為大寫單詞，下劃線分隔的命名方式。常量一定是static　final的字段，但是不是所有的static　final字段都是常量，例如：

static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");

5. 變量命名規范

非常量的變量（類變量和實例成員變量）名必須采用小寫單詞駝峰命名方式（lowerCamelCase）。

變量命名通常使用名詞和名詞短語，如computedValue、index。