“冗余”javadoc - 在面向公众的 API 中可取吗？答案

【问题标题】："Redundant" javadoc - desirable in public-facing APIs?“冗余”javadoc - 在面向公众的 API 中可取吗？
【发布时间】：2013-12-06 14:09:35
【问题描述】：

当你看到这样的东西时：

/**
* Gets the Person's identifier.
*
* @return The person identifier.
*/
public long getId()

很多人可能会想“重复代码所暗示的内容有什么意义”？我个人同意，如果我的代码只被我公司的人看到和使用，我不会费心写这样的评论。

但是，如果我正在编写一个 Apache Commons 库，我认为可以说它增强了消费程序员的体验。在 javadoc 中看到有空白区域的可访问方法只会给消费者一种缺乏友好/成熟/支持的感觉，这可能会影响他们对您的 api 的信心并最终选择竞争对手。

对于面向公众的 API 和非面向公众的 API，冗余 javadoc 的可取性是否存在差异？

【问题讨论】：

自我注意 - 1) 上面的评论很有帮助，因为它说明了标识符的用途。您不必转到 html 页面的顶部来查看 ID 用于哪个实体。 2) 与根本没有评论相比，没有任何有趣的冗余评论的存在是一个更强烈的信号，表明没有陷阱（类似于“关系数据库表中的空值可能意味着许多替代事物”）。

【解决方案1】：

所需的文档没有太大区别；您想知道的是症状而不是原因。在大多数情况下，糟糕的文档是因为您处于两种故障模式之一：

也许你有一种方法，它什么都不做，什么都不拥有，什么也不产生，所以在产品中没有有意义的角色。它的存在只是作为一袋比特将数据提供给其他人的一种方式，而不是做某事。

这导致了您所说的那种评论：“我所做的就是放弃对我的数据有意义的所有权，享受它。”没有什么可说的了，因为方法做什么都没有。

通过让您的对象拥有自己的数据来解决此问题。不要为某人构建访问器来读取它，构建执行他们需要的操作的方法并管理内部数据。构建对象拥有的渲染方法，而不是耸耸肩将 dava oer 交给第三方系统。

另一个可能的原因是您有一个听起来很简单的方法，例如“获取客户 ID”，但实际上确实有用。它是有目的的，它捕获了一堆业务逻辑，而你只是在描述中写下结果。

通过记录事情来解决这个问题。假设这不仅仅是“读取 ID”，我需要了解有关您的 API 的更多信息：

现在我知道它有一个 ID……某种……我可能会用来……不知道。识别事物？到，嗯，我猜是什么？

相反，我想知道这是唯一的 ID，它是稳定的，并且它可能会被重复使用，所以我不能在不订阅“用户已删除”通知的情况下将它藏在我身边，而且它需要一个数据库往返，但是一个 O(1) 的数据库操作，所以性能意味着网络上最少两次上下文切换和最多 12xRTT。

这些是您应该放入文档中的有用内容。然后在最后加上@returns the ID of the person，作为顶点。当然，我需要知道这一点，但我还需要了解更多才能有效和安全地使用它。

【讨论】：

您应该在列表中添加“ID 的值有什么保证？可以是null吗？null 是什么意思？”我已经开始使用 JSR 305 注释。编写 public setAge(@Min(0) @Max(120) final int newAge) 或相应的 getAge 访问器会自动用有用的信息填充 Javadoc。
有趣的观点丹尼尔。我是得墨忒耳法则的忠实拥护者，除了与类本身高度内聚的不可变或原始数据之外，我永远不会返回任何东西。

【解决方案2】：

如果您的意思是将其作为一个库，那么是的，所有公共方法和字段都应该记录在案，因为这就是生成 html 文档的来源。

对于个人使用或只是私有/受保护的方法，记录不言自明的内容没有多大意义。

【讨论】：

好的，这两个极端我完全同意。你在一个团队中工作的那个灰色区域怎么样？可能在地理上远程分布，但在你的团队之外没有人使用你的 API？我猜没有绝对正确或错误的做法，您必须单独对待每个案例？
我是我的代码，我通常不会记录 getter 和 setter 以及即使从名称上不言而喻的方法，但是“常规”方法通常值得拥有，因为您将在IDE 中的工具提示。但我想这完全是关于个人品味和你认为正确的事情。
很公平。回到公共图书馆的极端——你会为 html 文档记录“明显”的“官方”原因是什么？是因为您的听众可能包括非常缺乏经验的程序员吗？这是为了取悦营销部门的用户体验增强吗？还是说 html 文档应该被当作散文而不是代码来阅读？
我猜是为了保持一致性。当您阅读生成的文档页面时，那里有未记录的方法看起来有点不专业，特别是因为它们可能会有一些问题，比如它们在某些情况下返回 null，可能会引发运行时异常，或者只是一些实现细节和使用技巧。如果那里只有名称和参数，您可能想知道它是否真的如您所想。
这很有意义。谢谢 MightyPork。