gpt4 book ai didi

java - 执行 javadoc 注释

转载 作者:搜寻专家 更新时间:2023-10-31 19:36:44 25 4
gpt4 key购买 nike

我正在阅读很多关于 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);

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

最佳答案

在某种程度上,这是关于“风格”的。尽管如此,让我们来看看:

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

有些人认为拥有一定的值(value)

  • 人类可读的描述,告诉您方法的作用
  • 使用@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 行(只给出参数名称)显然是不行的。这些行告诉您什么 - 但您仍然需要花时间阅读并忽略它们。这样的东西是浪费。避免这种情况。

关于java - 执行 javadoc 注释,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/48522492/

25 4 0
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com