我正在阅读很多关于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);
是不是写了两次相同的东西?
答案 0 :(得分:8)
在某种程度上,这是关于“风格”。尽管如此,让我们来看看:
/**
* 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 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行(仅提供参数名称)是明确禁止的。这些行告诉你没有 - 但你仍然需要花时间阅读并忽略它们。这样的事情浪费。避免这样做。