[工具介紹] Java程式檢測工具(三) – DoctorJ & JCSC

前面我們介紹過 PMD 與 FindBugs 這兩個用來檢視 Java 程式碼 (Source Code 或是 ByteCode) 是否有問題產生的工具，這次我要介紹的兩個工具則是著重在檢測註解本身 (JavaDoc) 是否符合要求。為什麼會有這樣的需求？或許長久以來對於程式註解要包含哪些東西以及要如何撰寫沒有統一的共識，但是對於良好註解的重要性我想幾乎沒有人會加以反駁。良好的註解至少包含兩個重點，一致的格式與清楚且有意義的內容。清楚且有意義的內容有些抽象，但是一致的格式卻是可以明確的加以定義，所以我們訂定的寫作規範通常也會包含註解的格式。只是規定訂定下去以後，是否所有開發人員都會確實遵守又是另外一回事。在Code Review的時候一併檢驗？Code Review應該是用來找尋必須人工檢驗的問題，對於符合格式這種可以自動化的工作，用人工來做可是吃力不討好。透過使用 DoctorJ 或 JCSC，我們可以把格式確認的工作交由程式自動化執行，除了快速方便外，更可以避免開發人員因為抱持心存僥倖的心態而沒有撰寫合乎規範的註解。

DoctorJ 與 JCSC 在使用上都相當簡單，主要是透過命令列的形式。JCSC 另外提供了一個 GUI 的工具可供修改檢測的規則，而 DoctorJ 則沒有辦法修改檢測規則。但是 DoctorJ 可以一次檢測目錄下所有的程式檔，而 JCSC 則一次僅能檢測一個程式檔。嚴格說來，這兩個工具在使用的方便性都嫌不足，而且兩個工具也已經沒有再更新，不過這似乎是使用社群開發軟體常會遇到的問題。也因此要不要使用這些軟體，只能自己先好好做個評估了。

DoctorJ

1. 下載軟體。
2. 解開下載的軟體。
3. 打開 Microsoft Windows 的命令列模式。
4. 在解開的目錄下，執行 ant install 指令進行安裝的動作。沒有安裝 ant 的系統需先進行 ant 的安裝。
5. 雖然最後出現錯誤訊息，但是那僅是要將 jar 檔案複製時使用了 *nix 的路徑表示法，所以造成在 Microsoft Windows 無法執行。我們直接找到產生的 jar 檔案就可以了，該檔案為 share\doctorj\doctorj.jar。
6. 使用 doctorj 很簡單，只要透過 java –jar doctorj.jar filename|path 就可以進行檢測。 不過因為 doctorj 會將結果顯示於畫面上，所以我們可以透過轉向機制將結果儲存於檔案中。
   
   檢測單一的檔案
   檢測整個目錄
7. 使用文字編輯器打開儲存檢測結果的檔案。

JCSC

1. 下載軟體。
2. 解開下載的軟體。
3. 打開 Microsoft Windows 的命令列模式。
4. 在解開的目錄下，執行 bin\ruleseditor.bat。此工具可用來修改檢測的規則，其中針對註解的檢測規則在 JavaDoc 頁籤下。如果不需要修改直接選擇 “Close” 按鈕，修改資料後請記得選擇 “Save” 按鈕。
5. 使用 JCSC 非常簡單，只要透過指令 jcsc filename 即可。同樣的，JCSC 會將檢測結果直接輸出在畫面上，所以我們再次利用轉向的機制。
6. 使用文字編輯器打開儲存檢測結果的檔案。因為使用了 *nix 的換行符號，所以用記事本查看將會無法正常閱讀。我們看到檢測結果除了一般的違規事件說明外，也包含一些指標 (Metrics)。只可惜一次僅能針對一個檔案，需要透過額外的步驟才能得到整個專案的指標。
7. 雖然 JCSC 也能檢測其他的項目，但是因為其使用方便性遠不如 PMD 與 FindBugs，所以我就不加以說明了。

結語

雖然 DoctorJ 與 JCSC 在功能與使用方便性上都有不足之處，不過善加利用這些工具 (或其他類似的工具)可以讓我們強制執行 Java 程式註解的撰寫，以減少後續維護上的一些困擾。如果使用者可以透過自行撰寫的 script 或 ant task 提高這些檢測工作自動化的程度，對於程式的品質管理絕對會有相當的助益。