703
《數據結構與抽象：Java語言描述（原書第4版）》一P.2.1 注釋
本節書摘來華章計算機《數據結構與抽象：Java語言描述（原書第4版）》一書中的第1章 ，第1節，［美］弗蘭克M.卡拉諾（Frank M. Carrano） 蒂莫西M.亨利（Timothy M. Henry） 著 羅得島大學 新英格蘭理工學院 辛運幃 饒一梅 譯 更多章節內容可以訪問雲棲社區“華章計算機”公眾號查看。
P.2.1 注釋
現在來看看為類的方法而寫的注釋。雖然各組織有自己的注釋風格，但Java開發者有特定的應該遵從的注釋風格。如果程序中含有這種風格的注釋，則可以執行一個稱為javadoc的實用程序，從而得到描述類的文檔。這個文檔告訴未來使用這些類的人們必須了解的東西，但忽略了所有實現細節，包括所有的方法定義體。
程序javadoc提取類頭、所有公有方法的頭，及以特定形式寫的注釋。每個這樣的注釋必須出現在公有類定義或公有方法頭的前麵，且必須以/**開頭，以*/結尾。注釋中以符號@開頭的特定標簽（tag）標識方法的不同方麵。例如，使用@param標識參數，用@return標識返回值，而用@throws標識方法拋出的異常。本序言中，在注釋中會看到幾個這樣的標簽示例。附錄A詳述了如何書寫javadoc注釋。
現在不再進一步討論javadoc注釋的規則，而是要討論說明一個方法的重要方麵。首先，你需要寫一個簡潔的語句來闡述方法的目的或任務。這個語句以動詞開頭，能讓你避免冗長的文字，而那些文字真的是不需要的。
在思考方法的目的時，應該考慮它的輸入參數。如果有，要描述它們。還需要描述方法的結果。是讓它返回一個值、讓它做些動作，還是讓它改變參數的狀態？在寫這些描述時，應該時刻牢記以下理念。
最後更新：2017-06-26 14:02:13