Question

我正在阅读很多关于javadoc的文章，但是当这个＆＃34;样板＆＃34;开始。在这个例子中：

/**
 * 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行（仅提供参数名称）是明确禁止的。这些行告诉你没有 - 但你仍然需要花时间阅读并忽略它们。这样的事情浪费。避免这样做。

执行javadoc注释

1 个答案: