狗狗 |
2004-12-14 16:22 |
Java API 多得如恒河沙數,每個 Java 程式設計員都需要透過一套良好的 API 手冊來幫助撰寫程式。我心目中理想的 API手冊是像 The Waite Group 出版的《Win32 API Bible》,依功能將 API 分門別類,然後詳細介紹,還佐以短而具代表性的範例。
我認為 The Waite Group 出版的《Win32 API Bible》唯一的缺失在於它是印刷品。 API 手冊如果以紙張印刷的方式存在,儘管索引方式設計得再精良,查詢時仍然頗為費時、不便。更何況 Java 的 API 這麼多,真要印成手冊,恐怕會如大英百科全書般驚人。如果改以電子手冊的方式存在,並以 CD-ROM 的方式發行,無疑地是 Java API 手冊最好的現身方式,除了環保不需紙張的好處之外,查詢檢索起來更是方便,甚至可以使用交叉查詢的功能。
《Java Power Reference》是一份電子手冊,而且文件一律使用 HTML 的格式,所以可以直接用電腦上的瀏覽器閱讀,無須安裝特殊的電子書軟體。除了一片 CD-ROM 之外,《Java Power Reference》還附有一本薄薄的書(約六十頁),簡單地描述 Java 2 平台的現況。
《Java Power Reference》的優點包括了:
搜尋方式以及交叉索引都很方便,找資料的速度比 Sun 的線上說明快。 完整地列出 Java 2 所有的 API。包括了 182 package、3,900 個類別、38,384 個 methods 和 field 。(雖然如此,但其實資料量也只佔了光碟片的一小部分,約 130MB。) 雖然《Java Power Reference》是電子手冊,收集了齊全的 Java 2 API(包括了Core API 和 Standard Extension API),搜尋功能和索引作得不錯,也可以交叉查詢,但是 它卻讓我大失所望。任何人都可以輕易地發現《Java Power Reference》的兩大缺失:
沒有範例程式:你無法知道如何將這些 API 兜在一起,以達到特定功能。 沒有 API 說明:每個 method 只列出其傳入參數的型態和其傳出值的型態,其它的說明一概付之闕如。使用者只好透過 method 名稱來「望文生義」一番。 沒有範例、沒有 API 說明的 API 手冊,就好比是一本沒有例句、沒有單字說明的英文字典,我很懷疑這樣的字典能幫我寫好英文文章。對我來說,如果我想知道某 API 的用法,我寧願利用 Sun 提供的線上文件,因為它對每個 API 有詳細說明;如果我想快速查詢 API 格式,我會使用開發工具提供的提示功能(比方說 Jbuilder 的 CodeInside)。
希望在不久的未來《Java Power Reference》能改版,加強範例和 API 說明,成為真正的 Java POWER Reference。 |
|