文档化，只是返回的东西

我正在写一些的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，并避免在所有的评论。

我不能这样做（避免评论），所以我努力使它们尽可能有用。

来源

2010-11-29 Pablo Fernandez

恐怕你已经知道了答案。欢迎来到被称为无意义标准的地狱。 – riwalk 2010-11-29 19:19:21

太阳（现在是Oracle）的风格指南“How to Write Doc Comments for the Javadoc Tool”建议如下：

的@return标签需要每方法，返回非void东西，哪怕是多余与方法描述。（每当可能，找到非冗余（理想情况下，更具体的），以用于的标签注释。）

我不喜欢冗余的，它违背了DRY原则。就我个人而言，我要么做一个总结，要么做一个细节（如上面所建议的），或者只提供一个@return。正如你所指出的那样，一个简单的getter的名字可能就足够了。

来源

2010-11-30 04:47:25

最好是只提供@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(){

来源

2010-11-30 04:56:10

文档化，只是返回的东西

回答

相关问题