文檔化，只是返回的東西

Question

我正在寫一些的javadoc（實際上他們是jsdocs，但它不會使這個問題的不同），並發現這種重複圖案的方法：

試想一下，只是返回的方法價值，也許是一些計算的產物。例如，假設它是自unix時代以毫秒爲單位的時間。

public long getTimeSinceTheEpoch(){ 

    //calculate time 

    return time; 
} 

到目前爲止，這麼好。現在，在時機成熟時加入的javadoc（或jsdocs，或rdocs，等等），我已經寫了這樣的事情：

/** 
* Gets the time in milliseconds since the unix epoch 
* 
* @returns the time in milliseconds since the unix epoch 
*/ 
public long getTimeSinceTheEpoch(){ 

在這裏，問題是顯而易見的。

我的問題是，你在評論的正文中做了什麼，你對評論的@returns屬性選擇了什麼？

重要

我不是這幾樣的評論的粉絲，如果它依賴於我，我會重命名方法類似getTimeInMillisecondsSinceTheEpoch，並避免在所有的評論。

我不能這樣做（避免評論），所以我努力使它們儘可能有用。

Answer 1

太陽（現在是Oracle）的風格指南「How to Write Doc Comments for the Javadoc Tool」建議如下：

的@return標籤需要每 方法，返回非void東西 ，哪怕是多餘 與方法描述。 （每當 可能，找到非冗餘 （理想情況下，更具體的），以用於 的標籤註釋。）

我不喜歡冗餘的，它違背了DRY原則。就我個人而言，我要麼做一個總結，要麼做一個細節（如上面所建議的），或者只提供一個@return。正如你所指出的那樣，一個簡單的getter的名字可能就足夠了。

Answer 2

最好是隻提供@return描述，因爲您需要記錄您確定返回的內容。

在評論部分中，您也可以使用同樣的單行代碼，但也可以添加如何您將返回返回的內容，例如，

/** 
* Gets the time in milliseconds since the unix epoch 
* by doing something incredible. 
* http://stackoverflow.com/questions/4307142/documenting-a-method-that-just-returns-something 
* 
* @note thank you stackoverflow 
* 
* @returns the time in milliseconds since the unix epoch 
*/ 
public long getTimeSinceTheEpoch(){