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

　　之所以把Java注釋和文檔功能放在最前面介紹，是因?yàn)镴ava程序的理念使然——所謂兵馬未動(dòng)糧草先行。

　　幾乎所有編程語(yǔ)言都提供在源代碼中添加注釋的功能，開(kāi)發(fā)者通過(guò)注釋給自己或代碼的閱讀者進(jìn)行備忘或提示，好比讀書(shū)時(shí)在書(shū)上的空白處寫(xiě)筆記，或在屋子里使用N次貼。Java語(yǔ)言一個(gè)優(yōu)秀思想便是——編寫(xiě)源代碼并非唯一重要的工作，給源代碼加上詳細(xì)的注釋同樣重要。道理很簡(jiǎn)單，源代碼和Java的字節(jié)碼不同，字節(jié)碼是給電腦看的，而源代碼是給人閱讀的，沒(méi)有好的文檔與注釋?zhuān)�閱讀源代碼必須猜測(cè)源代碼作者的意圖，勢(shì)必枯燥而且效率低下。

　　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語(yǔ)言繼承過(guò)來(lái)的風(fēng)格，注釋從/*開(kāi)始，到*/結(jié)束，它們必須成對(duì)使用，之間可以換行。Hello World!程序開(kāi)頭部分就是這種風(fēng)格的注釋?zhuān)�記載著這個(gè)源程序的創(chuàng)始時(shí)間和一些提示。許多程序員為了美觀，喜歡在多行注釋前加入一個(gè)*符號(hào)，從而就形成了上面的格局。當(dāng)然，這個(gè)注釋的內(nèi)容是Eclipse自動(dòng)生成的，你可以通過(guò)修改Eclipse的代碼模板來(lái)修改自動(dòng)生成的內(nèi)容。
第二種注釋是從C++語(yǔ)言繼承過(guò)來(lái)的單行注釋風(fēng)格，注釋從//開(kāi)始，一直到這行結(jié)束。這種風(fēng)格的注釋非常容易使用，你不必低頭在鍵盤(pán)上連續(xù)尋找/和*鍵，只需要連續(xù)按下/鍵兩次。同時(shí)，不需要像C語(yǔ)言風(fēng)格注釋那樣特意使注釋符號(hào)配對(duì)。Hello World!程序中“// 打印Hello World!字樣”就是這種風(fēng)格的注釋。

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

　　我們還是結(jié)合Eclipse來(lái)說(shuō)明Java文檔的應(yīng)用。首先在Eclipse中打開(kāi)Hello World!程序。試試看把鼠標(biāo)移動(dòng)到HelloWorldApp字符上面去，是不是顯示了如圖1所示的效果(圖1  Eclipse自動(dòng)顯示Java文檔的功能)？

　　沒(méi)錯(cuò)，當(dāng)你把鼠標(biāo)移動(dòng)到一個(gè)Java類(lèi)、變量或方法上，Eclipse將通過(guò)代碼分析技術(shù)在源代碼中萃取出相應(yīng)的Java文檔并且顯示給你看，如果該Java元素有文檔的話。
下面讓我們?yōu)閙ain方法編寫(xiě)Java文檔來(lái)親自體驗(yàn)一下。首先把光標(biāo)移動(dòng)到public class HelloWorldApp {之后并回車(chē)以便插入一空白行。然后，輸入/**并且回車(chē)，你會(huì)發(fā)現(xiàn)Eclipse自動(dòng)為你生成如一個(gè)Java文檔塊，并且自動(dòng)識(shí)別出main方法有一個(gè)名為args的參數(shù)(很神奇吧？)。把該文檔改寫(xiě)成這樣:

/**
* 這是主函數(shù)，程序?qū)�從這里開(kāi)始運(yùn)行。
* @param args 命令行參數(shù)
*/

　　然后你把鼠標(biāo)移動(dòng)到main上面，是不是得到明明白白的文檔信息了？

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

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

　　Eclipse默認(rèn)使用JRE作為Java虛擬機(jī)。然而，使用J2SE SDK本身是更好的選擇，因?yàn)槟憧梢蚤_(kāi)啟查看Java API文檔的重要功能，這對(duì)于提高軟件的開(kāi)發(fā)效率以及深刻體驗(yàn)Eclipse，有著重要意義。方法如下:

　　1.依次點(diǎn)擊Eclipse菜單項(xiàng)中的Windows、Preferences。

　　2.展開(kāi)Java/Installed JRE，按下Add，按照?qǐng)D2所示填寫(xiě)參數(shù)(圖2   完成后按下OK鍵)。

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

　　好了，現(xiàn)在把光標(biāo)移動(dòng)到println上看看是不是和圖3所示一樣呢(圖3)？

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

　　順便說(shuō)一句，Java還提供了從源代碼中自動(dòng)萃取Java文檔，生成HTML文件以便單獨(dú)閱讀的機(jī)制，那就是J2SE SDK提供的javadoc工具。在Eclipse中，可以通過(guò)File菜單中的Export選項(xiàng)進(jìn)行操作。

　　Just do it

　　試試把HelloWorldApp的Java文檔改得更有調(diào)理，并且修改author屬性成為你的名字。然后通過(guò)Eclipse內(nèi)置的javadoc輸出功能生成該項(xiàng)目的Java文檔，感受一下Java文檔代碼并重的開(kāi)發(fā)理念。

　　Java文檔是一門(mén)學(xué)問(wèn)。除了上面用到的param和author標(biāo)簽，Java文檔還支持許多特定的標(biāo)簽，可以直接內(nèi)嵌HTML代碼以便得到優(yōu)美的輸出，還可以通過(guò)doclets自行擴(kuò)展javadoc的處理機(jī)制。完整的說(shuō)明文檔請(qǐng)參考C:\j2sdk1.4.2_04\docs\tooldocs\windows\javadoc.html。