Java 程式註解統一格式

 
/* 
 * Copyright 2002 Database Systems, CSE, NSYSU. All rights reserved. 
 * File: UtilityFunction.java 
 * User: Wei-horng Yeh 
 * Date: 2002/9/9 
 * Version: 1.0 
 * Since: JDK 1.4.0 
 */ 
package tw.edu.nsysu.cse.db; 
 
/** Class UtilityFunction provide some simlpe fuctions such as Quick Sort, 
 *  Swap, etc. 
 */ 
public class UtilityFunction { 
  /** It is used for function testing */ 
  private int[] arrayInt = new int[]{3, 9, 4, 8, 1, 7, 6}; 
 
  /** 
   * Interchange v[i] and v[j]. 
   * @param  v  The array which its entities will be interchanged. 
   * @param  i  The index for the first entity. 
   * @param  j  The index for the second entity. 
   * @return No return value. 
   */ 
  public static void swap(int[] v, int i, int j) { 
    /* to store the first element value */ 
    int temp; 
 
    // Interchange the target values. 
    temp = v[i]; 
    v[i] = v[j]; 
    v[j] = temp; 
  } 
} 
 

上面灰底綠字的內容表示每個檔案的檔頭，檔頭必須用 block comment(/**/) 的註解

 格式包覆起來，內容要包括「著作權宣告」、「檔案名稱」、「程式碼的作

 者」、「程式編寫日期」、「程式版本」和「編譯器版本」。

 
 
/* 
 * Copyright 2002 Database Systems, CSE, NSYSU. All rights reserved. 
 * File: UtilityFunction.java 
 * User: Wei-horng Yeh 
 * Date: 2002/9/9 
 * Version: 1.0 
 * Since: JDK 1.4.0 
 */ 
package tw.edu.nsysu.cse.db; 
 
/** Class UtilityFunction provide some simlpe fuctions such as Quick Sort, 
 *  Swap, etc. 
 */ 
public class UtilityFunction { 
  /** It is used for function testing */ 
  private int[] arrayInt = new int[]{3, 9, 4, 8, 1, 7, 6}; 
 
  /** 
   * Interchange v[i] and v[j]. 
   * @param  v  The array which its entities will be interchanged. 
   * @param  i  The index for the first entity. 
   * @param  j  The index for the second entity. 
   * @return No return value. 
   */ 
  public static void swap(int[] v, int i, int j) { 
    /* to store the first element value */ 
    int temp; 
 
    // Interchange the target values. 
    temp = v[i]; 
    v[i] = v[j]; 
    v[j] = temp; 
  } 
} 
 

淺灰色字體的內容表示和類別有關的註解，包含類別的 fields 和 method，其程式註解必須用特定的 Java Document Comment(/** */)，註解之後請緊接著 class、fields 和 methods 的定義。

 

Class 註解的內容請概略地描述此類別的功能，可以參考 Sun® Microsystems 提供的線上 Java Help 關於類別的描述方式。

 

Field 註解的內容請概略地描述此資料成員的用處，可以參考 Sun® Microsystems 提供的線上 Java Help 關於資料成員的描述方式。

 

Method 註解的內容較為繁雜，在註解啟始處描述此成員函式的作用，接著使用 Java Document Comment 中的特殊註解符號「@param」和「@return」來分別描述函式每個參數和回傳值的意義，描述的詳細程度，可以參考 Sun® Microsystems 提供的線上 Java Help 關於類別的描述方式。

 
 
/* 
 * Copyright 2002 Database Systems, CSE, NSYSU. All rights reserved. 
 * File: UtilityFunction.java 
 * User: Wei-horng Yeh 
 * Date: 2002/9/9 
 * Version: 1.0 
 * Since: JDK 1.4.0 
 */ 
package tw.edu.nsysu.cse.db; 
 
/** Class UtilityFunction provide some simlpe fuctions such as Quick Sort, 
 *  Swap, etc. 
 */ 
public class UtilityFunction { 
  /** It is used for function testing */ 
  private int[] arrayInt = new int[]{3, 9, 4, 8, 1, 7, 6}; 
 
  /** 
   * Interchange v[i] and v[j]. 
   * @param  v  The array which its entities will be interchanged. 
   * @param  i  The index for the first entity. 
   * @param  j  The index for the second entity. 
   * @return No return value. 
   */ 
  public static void swap(int[] v, int i, int j) { 
    /* to store the first element value */ 
    int temp; 
 
    // Interchange the target values. 
    temp = v[i]; 
    v[i] = v[j]; 
    v[j] = temp; 
  } 
} 
 

黃底綠字的內容是用來註解類別中每個method裡頭所用到的區域變數以及程式區塊 (if else statement、for loop、while loop…等等)，這裡有兩種不同的註解格式。

 

區域變數請使用 block comment (/* */) 註解格式，說明區域變數的用處。

 

程式區塊請使用 line comment (//) 註解格式，註解內容請詳細描述此程式區塊在做些什麼事。

 

最後該注意的是，程式碼每列最大的長度為 80 columns。