在 Java 中记录第三方库的使用的标准/官方方式是什么？答案

【问题标题】：What's the standard/official way for documenting the use of a third party library in Java?在 Java 中记录第三方库的使用的标准/官方方式是什么？
【发布时间】：2014-03-19 03:18:51
【问题描述】：

在使用第三方库的类之前编写 javadoc 注释时，记录第三方库名称、版本和可以下载的网址的标准/官方方式是什么？是否应该在描述中或块标签中提及（使用@see 或自定义标签）？

【问题讨论】：

对此没有最佳实践。做任何你公司或组织的规则，或者你认为最好的任何事情。
我只想说个好问题。我希望更多的人思考这个问题。但是，我认为大多数开发人员只会说它由 import 语句记录，那么为什么要在 Javadoc 中提及它呢？由于这可能是大多数人的意见，我怀疑是否存在最佳实践。最好只创建自己的标准并在这个特定的库中始终如一地遵循它。
我同意 Scott 的看法，但不同意票数接近的投票 - 没有对此有固定的约定，但这仍然是一个好问题，即使答案很简单“没有。”
这个问题在 StackExchange 站点 programmers.stackexchange.com 上可能更合适。

标签： java javadoc

【解决方案1】：

取决于你想要完成什么。

版本和下载链接应该在你的依赖管理工具（如maven）的配置文件中。这样，文档永远不会过时，并且不会在碰巧使用该特定 API 的每个类中重复。

要发现哪些类使用哪些 API，import 语句可以很好地工作（是的，可以通过使用限定的类名绕过 import 语句，但很少有人这样做，因为这使得源代码很难阅读）。或者，只需从类路径中删除该库，然后查看发生编译错误的位置。

我建议不要在 javadoc 中记录这一点，因为你的类的调用者应该不知道它的实现。也就是说，我认为 API 曾经是调用者不应该知道的实现细节——调用者不应该知道的东西不应该与他必须知道的东西混在一起。

【讨论】：

【解决方案2】：

是否应该在描述中或块标签中提及（使用@see 或自定义标签）？

只需在描述中的某处提及它，（个人）最好在结尾处提及。不要为这样的东西定义自定义标签，这不值得麻烦。重要的是（如有必要）信息就在那里。这样做没有固定的约定。

我故意说“如果有必要” - 大多数时候我会说这根本不需要。但是，如果处理一个不广为人知的库，不在 Maven 中和/或有在版本之间进行重大更改的倾向，那么至少在某个地方记录这一点可以说是值得的。

【讨论】：