記錄獲取者和設置者

對於簡單的獲取者/設置者，如下所示，記錄它的最佳方式是什麼？記錄獲取者和設置者

public float getPrice() 
{ 
    return price; 
}

我很嚴格的有關編碼標準，所以我的IDE警告我，任何無證公共/保護方法。

選項1：

/** 
* Get the price field. 
* 
* @return 
*/

選項2：

/** 
* @return Price 
*/

還是不要在所有文件呢？

來源

2010-08-30 Amy B

可能重複[Simple Getter/Setter comments]（http://stackoverflow.com/questions/1028967/simple-getter -setter-comments） – Raedwald 2016-04-01 12:51:07

我會寫最低限度保持棉絨安靜。如果這是顯而易見的是什麼的getter/setter越來越/設置，我會使用一些複製粘貼文件，使得它清楚地表明沒有任何幻想是怎麼回事：

/** 
* Simple getter. 
* @return Price 
*/

我個人認爲太多的getter和setter方法是這是一種代碼異味，因爲這可能表明你沒有在正確的抽象層次上提供操作（這顯然不總是對的，而是一種經驗法則）。

來源

2010-08-30 01:42:25

記錄界面，就好像用戶對實施一無所知。這些文檔適用於該方法的調用者，他們不必知道或關心具體的內部狀態，但必須關心該方法對他們所做的工作。

來源

2010-08-30 01:48:38

我一直在尋找，直到我如此搜查，發現使用人DOCO功能的標準方式： GhostDoc - http://submain.com/products/ghostdoc.aspx

它的最好的汽車DOCO工具之一，在那裏，每一種格式的您的意見以同樣的方式。最好的情況是，如果你的方法被恰當地命名，那麼你甚至不需要編輯自動生成的doco，因爲它是有意義的。

此外，當您使用intellisense時，評論會出現，因此您可以提醒您代碼在您寫完一個月後會做些什麼！ :)

GhostDocs會這樣對你的財產：（快捷鍵Ctrl + Shift + d）

/// <summary> 
    /// Gets the price. 
    /// </summary> 
    /// <returns></returns> 
    public float getPrice() 
    { 
     return price; 
    }

來源

2010-08-30 01:51:52 Joe

GhostDoc不支持Javadoc。 – 2010-09-03 21:38:58

嗯，傻我錯過了javadoc標籤。 – Joe 2010-09-04 08:36:13

及其唯一有用的視覺工作室 – UpAndAdam 2014-03-13 16:02:03

描述最小另一個程序員理解什麼方法做或退貨。

我這樣做：

/** 
* @return the price. 
*/

或

/** 
* Returns the prize. 
* 
* @return the price. 
*/

這重複了相同的文字，但如果你同意在需要的描述，而不是隻有某些編碼標準，可能有必要標籤。

我不會提及它返回價格字段，因爲它描述了內部表示。

來源

2010-08-30 10:51:05 Kwebble

如果「價格」不是最明顯的價值，那麼您的評論應該描述「價格」的含義和用途，而不僅僅是它的名稱。

一些假設的例子：

是它的「稅前價」或「含稅價」？
它是以美元，歐元還是英鎊表示？
它是四捨五入到最接近的分，5美分還是美元？
是否返回特殊值以指示免費項目（例如0.0f）？
價格是否可以「未初始化」？如果是，返回什麼值（例如-1.0f）？

有關方法和屬性的一個很好的比例，有東西你可以說，告訴讀者不僅僅是名字會告訴他們。這可以節省其他程序員很多時間並降低bug的風險。即使它僅僅證實了他們的猜測/假設，仍然會爲他們節省時間。

對於完全不言自明的「簡單」值（例如Rectangle.Width），請不要浪費時間打字 - AtomineerUtils將通過單次按鍵爲您創建文檔級別。（AtomineerUtils的優勢在於它支持Doxygen，Javadoc和文檔XML註釋格式以及VB，C＃，C++/CLI，C++和C代碼，因此您可以保留現有格式，同時大幅縮短您花費的時間文檔評論GhostDoc會做類似的工作，但它只支持VB和C＃的Xml文檔）

來源

2010-09-03 21:43:09

記錄獲取者和設置者

回答

相關問題