Java文檔中的私有成員變量

Question

getter/setter使用的私有成員變量爲什麼要在描述相應獲取器和設置器的javadoc中指定其描述。

Answer 1

私有變量的描述，喜歡這裏：

/** 
* the name of this object. 
*/ 
private String name; 

...不應該包含其getter和setter方法的說明。它應該包含這個變量的屬性，不變式（如絕不能爲空）等等。

---

編輯： 啊，我誤解了你的問題。你問爲什麼getters/setters的描述應該包含變量的描述，而不是相反。

他們不應該 - 甚至不必存在這樣的變量。吸氣人員和安裝人員應描述他們所具有的效果，其中可能包括修改（或檢索）此物體的某些抽象屬性。這個屬性是由私有變量實現的並不相關。

Answer 2

JavaDocs的目的是記錄代碼的公共API，以便開發人員能夠理解如何使用您的類。目的不是揭露你的代碼的內部運作。記錄私人成員只會讓你的API文檔更難閱讀。

私人成員的含義只對那些閱讀/維護您的代碼感興趣。他們的目的應該通過清晰明確的命名和代碼的普遍優雅來傳達。理想情況下，你甚至不需要評論。