Question

我正在编写一些javadocs（实际上它们是jsdocs，但它对这个问题没什么影响）并找到了这个重复的模式：

想象一个只返回一个值的方法，可能是某些计算的结果。例如，假设它是自unix时代以来的毫秒数。

public long getTimeSinceTheEpoch(){

  //calculate time

  return time;
}

到目前为止，这么好。现在是时候添加javadocs（或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

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

Answer 2

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

每个人都需要@return标签返回其他东西的方法而不是无效，即使它是多余的用方法描述。（每当可能，找到一些非冗余的东西（理想情况下，更具体）用于标签评论。）

我不喜欢冗余，这违反了DRY原则。就个人而言，我要么是一个摘要，另一个是细节（如上所述），或只提供@return。正如您所指出的，简单的getter的名称可能足以作为摘要。

记录一个只返回一些东西的方法

2 个答案: