“冗余”javadoc - 面向公众的API是理想的吗？

Question

当你看到这样的事情时：

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

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

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

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

Answer 1

如果你把它当作一个库，那么是的，所有的公共方法和字段都应该被记录下来，因为这就是生成html文档的内容。

对于个人用途或仅仅是私人/受保护的方法，记录不言而喻的内容并不重要。

Answer 2

所需的文档没有太大差异;你想知道一个症状而不是一个原因。在大多数情况下，可怕的文档是因为您处于两种失败模式之一：

也许你有一种方法什么也不做，什么都不拥有，什么也没有，所以在产品中没有任何有意义的作用。它只是作为一个包的方式来向其他人提供数据，而不是做某事。

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

。

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

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

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

• 这是一个持久性标识符，我可以存储在我的数据库中，并用于以后获取该人吗？
• 它会改变吗？当？
• 这是普遍独特的还是本地独一无二的？
• 当数字空间用完时会发生什么？
• 应该向用户显示，还是严格内部编号？
• 是否有任何安全方面的考虑因素，因此暴露它可能会产生产品安全问题？
• 是快还是慢 - 我可以在性能关键位置调用它吗？
• 它有效期多久 - 我可以将它缓存在循环的顶部并在整个过程中使用吗？
• 我可以将其他相关API传递给系统以进行有意义的更改吗？

现在我知道它有一个ID ...某种......我可能会用......不知道。识别事物？嗯，嗯，我猜？

相反，我想知道这是唯一的ID，它是稳定的，并且它可能被重用，所以我不能在没有订阅“用户删除”通知的情况下将它存放在我身边，并且它需要数据库往返，但需要O（1）数据库操作，因此性能意味着网络中至少有两个上下文切换和最多12xRTT。

这些是你应该放入文档的有用的东西。然后在最后有@returns the ID of the person作为顶点。我需要知道，当然，但我需要知道更多有效和安全地使用它。