Z05 版權宣告與註解範本的內容

撰寫程式碼除了code本身之外，每一支程式都必須要有的部分就是版權宣告與程式碼註解。每支程式最前端都會有我自己的版權宣告段落：

/*******************************************************************************
* Copyright (c) 2010 Joying Lee
*
* All rights reserved.
* This program is free to use, but the ban on selling behavior.
* Modify the program must keep all the original text description,
* and can only comment out the original code (not allowed to delete).
*
* 保留所有權利。
* 本程式可任意使用，但是禁止販售行為。
* 修改程式時必須保留所有原有文字說明，而且只能註解掉原來的程式碼 (不允許刪除)。
*
* My Blog : http://ooadreason.blogspot.com
*******************************************************************************/

註解的定義根據[V01]的描述，區分為Class、Field與Method三種；註解的本體目前定義有摘要、描述與使用三個部分，再往下則是@開頭的Java Doc常用標籤。整理為出一份自己要使用的關係對照表如下圖，接著遵循這些註解規則建立Eclipse內的Code Template並匯出XML作為往後使用的標準。



最後定義程式中描述處理過程的註解與變更時與Trac ticket相關的標記註解如下：

/* 這是描述處理過程的註解，必須獨立存在一行 */
// 這是與Trac ticket相關的標記註解，必須在程式碼那行的最後面

註：在以下範例程式的三個註解位置，似乎各自代表不同的意義。我的解讀是：
註解Ａ－描述if那個指令的判斷說明。
註解Ｂ－描述if成立後那個block的說明。
註解Ｃ－描述return那行的說明。
/* 註解A */
if (isTrue()) /* 註解B */ {
　　/* 註解C */
　　return;
}
若依照我的註解準則與未來模組化的目的，應該變成可讀性略差的這樣：
/* 註解A */
if (isTrue())
/* 註解B */
{
　　/* 註解C */
　　return;
}

參考網址：http://java.sun.com/j2se/javadoc/writingdoccomments/index.html