Java咖啡館——品味首杯咖啡（1）

　　之所以把Java注釋和文檔功能放在最前面介紹，是因為Java程序的理念使然——所謂兵馬未動糧草先行。

　　幾乎所有編程語言都提供在源代碼中添加注釋的功能，開發者通過注釋給自己或代碼的閱讀者進行備忘或提示，好比讀書時在書上的空白處寫筆記，或在屋子里使用N次貼。Java語言一個優秀思想便是——編寫源代碼并非唯一重要的工作，給源代碼加上詳細的注釋同樣重要。道理很簡單，源代碼和Java的字節碼不同，字節碼是給電腦看的，而源代碼是給人閱讀的，沒有好的文檔與注釋，閱讀源代碼必須猜測源代碼作者的意圖，勢必枯燥而且效率低下。

　　Java中的注釋一共有兩種，我們的Hello World!程序麻雀雖小但是五臟俱全，全部都用到了。下面是Hello World!程序的源代碼:

/*
* Created on 2004-6-4
*
* TODO To change the template for this generated file go to
* Window - Preferences - Java - Code Style - Code Templates
*/

/**
* @author gary chan
*
* TODO To change the template for this generated type comment go to
* Window - Preferences - Java - Code Style - Code Templates
*/
public class HelloWorldApp {

    public static void main(String[] args) {
        // 打印Hello World!字樣
        System.out.println("Hello World!");
    }
}

　　第一種注釋是從C語言繼承過來的風格，注釋從/*開始，到*/結束，它們必須成對使用，之間可以換行。Hello World!程序開頭部分就是這種風格的注釋，記載著這個源程序的創始時間和一些提示。許多程序員為了美觀，喜歡在多行注釋前加入一個*符號，從而就形成了上面的格局。當然，這個注釋的內容是Eclipse自動生成的，你可以通過修改Eclipse的代碼模板來修改自動生成的內容。
第二種注釋是從C++語言繼承過來的單行注釋風格，注釋從//開始，一直到這行結束。這種風格的注釋非常容易使用，你不必低頭在鍵盤上連續尋找/和*鍵，只需要連續按下/鍵兩次。同時，不需要像C語言風格注釋那樣特意使注釋符號配對。Hello World!程序中“// 打印Hello World!字樣”就是這種風格的注釋。

　　如果你的洞察力敏銳，你會發現Hello World!程序中還有一處用/**和*/包裹起來的的代碼并不屬于以上任何一種注釋。沒錯，這是Java文檔(Java documentation)。文檔與注釋不同，注釋一般比較隨意，反映的是局部語句的功能或聲明，而文檔是與代碼的結構相關的，好比是代碼的摘要，給人一個結構化的總體觀念。特別地，Java文檔所注釋的，是緊隨其后的類、變量或方法。

　　我們還是結合Eclipse來說明Java文檔的應用。首先在Eclipse中打開Hello World!程序。試試看把鼠標移動到HelloWorldApp字符上面去，是不是顯示了如圖1所示的效果(圖1  Eclipse自動顯示Java文檔的功能)？

　　沒錯，當你把鼠標移動到一個Java類、變量或方法上，Eclipse將通過代碼分析技術在源代碼中萃取出相應的Java文檔并且顯示給你看，如果該Java元素有文檔的話。
下面讓我們為main方法編寫Java文檔來親自體驗一下。首先把光標移動到public class HelloWorldApp {之后并回車以便插入一空白行。然后，輸入/**并且回車，你會發現Eclipse自動為你生成如一個Java文檔塊，并且自動識別出main方法有一個名為args的參數(很神奇吧？)。把該文檔改寫成這樣:

/**
* 這是主函數，程序將從這里開始運行。
* @param args 命令行參數
*/

　　然后你把鼠標移動到main上面，是不是得到明明白白的文檔信息了？

　　實際上，Java文檔功能是貫穿于Java語言中的重要功能。但當你把光標移動到System.out.println("Hello World!")語句上，卻得不到有用的含義以及參數的用法，該語句還是Java內置的API呢。怎么會這樣子？

　　聰明的你一定想到答案了——一定是Java API的Java文檔沒有配置好嘛。沒錯，J2SE SDK并不包含Java API的Java文檔，需要單獨下載。你可以從http://java.sun.com/j2se/1.4.2/download.html下載到J2SE 1.4.2的文檔，如果你從國外下載不方便，還可以到http://garychan.3322.org的Java資源欄目下載，約32.80MB。下載以后請把壓縮包中的doc目錄解壓縮到C:\j2sdk1.4.2_04\中。

　　Eclipse默認使用JRE作為Java虛擬機。然而，使用J2SE SDK本身是更好的選擇，因為你可以開啟查看Java API文檔的重要功能，這對于提高軟件的開發效率以及深刻體驗Eclipse，有著重要意義。方法如下:

　　1.依次點擊Eclipse菜單項中的Windows、Preferences。

　　2.展開Java/Installed JRE，按下Add，按照圖2所示填寫參數(圖2   完成后按下OK鍵)。

　　3.在Installed JREs對話框中的J2SDK 1.4.2_04前面打上勾，按下“OK”關閉Preferences對話框。Eclipse會提示你需要重新編譯一次，“OK”即可。

　　好了，現在把光標移動到println上看看是不是和圖3所示一樣呢(圖3)？

　　怎么樣，該方法的詳細使用說明都有了吧？如果內容比較多，按下F2鎖定之后便可以察看全部的信息。以后有什么API不明白，不用苦苦上網搜索了，Java API文檔本身就是Java API的大百科，再配合Eclipse的自動顯示功能，實在方便得不行。

　　順便說一句，Java還提供了從源代碼中自動萃取Java文檔，生成HTML文件以便單獨閱讀的機制，那就是J2SE SDK提供的javadoc工具。在Eclipse中，可以通過File菜單中的Export選項進行操作。

　　Just do it

　　試試把HelloWorldApp的Java文檔改得更有調理，并且修改author屬性成為你的名字。然后通過Eclipse內置的javadoc輸出功能生成該項目的Java文檔，感受一下Java文檔代碼并重的開發理念。

　　Java文檔是一門學問。除了上面用到的param和author標簽，Java文檔還支持許多特定的標簽，可以直接內嵌HTML代碼以便得到優美的輸出，還可以通過doclets自行擴展javadoc的處理機制。完整的說明文檔請參考C:\j2sdk1.4.2_04\docs\tooldocs\windows\javadoc.html。