执行 javadoc 注释

Question

我正在阅读很多关于javadoc的文章，但是当"样板"开始时仍然无法理解。在此示例中：

/**
* Returns a list of tasks for specific user
* @param userId
* @return Selected list of tasks
*/
List<Task> getTasksForUser(Integer userId);
/**
* Returns a list of tasks in chosen month and year
* @param month
* @param year
* @return selected list of tasks
*/
List<Task> getTasks(Integer month, Integer year);

我可以以某种方式执行它们以减少样板还是应该删除它们？

为什么在75%的文章中被称为"Javadoc的最佳实践"，我们有重复？ 例如：

/**
* Returns a list of tasks using params month, year
* @param month
* @param year
* @return a list of tasks
*/
List<Task> getTasks(Integer month, Integer year);

不是写了两倍一样的东西吗？

Answer 1

在某种程度上，这是关于"风格"的。尽管如此，让我们来看看：

/**
* Returns a list of tasks for specific user
* @param userId
* @return Selected list of tasks
*/
List<Task> getTasksForUser(Integer userId);

有些人认为拥有一定的好处

• 人类可读的描述，告诉您方法的作用
• 使用 @param/@return 标签的其他信息

例如，您可以像这样重写它：

/**
* Returns a list of tasks for specific user.
* @param userId denotes the user by his numeric id
* @return Selected list of tasks (maybe empty, never null)
*/
List<Task> getTasksForUser(Integer userId);

所以 - 在你的例子中，有空间使用额外的标签来提供实际上不同的信息：我的版本中的每一行都有一定的目的，而你的例子只是重复相同的信息，尽管使用的措辞略有不同。

但如前所述，归根结底，这是一个风格问题，关键是：你应该选择你(和你的同龄人)认为对你的语境最有帮助的"风格"。

请注意：与其一遍又一遍地重复"明显"的事情，更有用的评论可能看起来像这样：

/**
* @return The tasks selected for the given user (maybe empty, never null)
* @throws UnknownUserException when <code>userId></code> is not known
*/
List<Task> getTasksForUser(Integer userId);

这基本上是"我"的首选风格 - 使用单@return行。但相反，请提及关键方面，例如 - 如果......

最后一点：拥有"空"@param行(仅提供参数名称)显然是不行的。这些行什么也没告诉你——但你仍然需要花时间阅读和忽略它们。这样的东西是浪费。避免这种情况。