执行 javadoc 注释

Question

我正在阅读很多关于 javadoc 的文章，但在 "boilerplate" 开始时仍然无法处理。在这个例子中：

/**
 * 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);

不就是写了2次一样的东西吗？

Answer 1

在某种程度上，这大约是"style"。尽管如此，让我们来看看：

/**
 * 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);

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

但如前所述，归根结底，这是风格问题，关键是：您应该选择 "style" 您（和您的同龄人）认为对您的工作最有帮助的语境。

请注意：不要一遍又一遍地重复 "obvious" 事情，更有帮助的评论可能看起来像这样：

/**
 * @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);

这基本上是 "my" 首选样式 - 使用单个 @return 行。而是提及关键方面，例如 - 如果...

，此方法将抛出运行时异常

最后一点：使用 "empty" @param 行（只给出参数名称）显然是不行的。这些行告诉你什么都没有 - 但你仍然需要花时间阅读和忽略它们。这样的东西浪费。避免这种情况。

执行 javadoc 注释

Performing javadoc comments

java

javadoc