V01 註解的存取(1)──定義註解的格式

以下的各種註解範例取自於JDK 5.0裡頭的java.lang.StringTokenizer。

/**
* Class Description....
*
* @author Lee Boynton
* @author Arthur van Hoff
* @version 1.189, 10/21/05
* @see java.lang.Object#toString()
* @see java.lang.StringBuffer
* @see java.lang.StringBuilder
* @see java.nio.charset.Charset
* @since JDK1.0
*/
這是Java Doc對Class的註解範例。很明顯地具有描述的本體與下面用＠符號開頭的屬性，屬性可能具有多個值。

/** Field Description.... */
private final char value[];
這是Java Doc對Data的註解範例。只擁有描述本體而沒有任何屬性的結構，很明顯地是Class註解的子集合。

/**
* Method Description....
*
* @param codePoints array that is the source of Unicode code points.
* @param offset the initial offset.
* @param count the length.
* @exception IllegalArgumentException if any invalid Unicode code point
* is found in codePoints
* @exception IndexOutOfBoundsException if the offset
* and count arguments index characters outside
* the bounds of the codePoints array.
* @since 1.5
*/
public String(int[] codePoints, int offset, int count) {
}
這是Java Doc對Method的註解範例。註解的屬性名稱雖與Class註解有所出入，但是基本的結構是一致的。

/* Reset these anyway */
delimsChanged = false;
// The array representing the String is the same
// size as the String, so no point in making a copy.
v = originalValue;
從String與StringTokenizer裡發現兩種不同的註解類型，都是合法的Comment。它們都只具有描述的本體而沒有任何屬性，與Data的註解結構相同。

2000年的時候曾經維護過某大公司應用在銀行的大型產品程式碼，註解裡鉅細靡遺地記錄著對應程式碼的修改歷程，每筆記錄存放了修改日期、修改人員與修改原因的資訊，同時Class上也收集了Class內所有的修改記錄，看起來非常地清楚。因此在註解的設計裡同樣選擇採用這個制度，讓修改歷程放在註解裡跟著程式碼走，額外再使用Java Doc的標籤讓這些記錄可以出現在產出文件裡。（以前的產品只能用文字搜尋）

U22提到了收集所有註解另外處理的功能，經過收集後的註解已經與程式碼脫離，所以需要額外的欄位來定義與其相關的程式部位：Class、Data註解需要記載屬於哪一個Class，Method、Comment註解需要記載屬於哪一個Class的Method，將這些資訊定義在一個關聯用的Attribute（id）裡。

以上是註解Data Model結構（U23）的基本設計依據。