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

Question

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

Answer 1

取决于你想完成什么。

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

要发现哪些类使用哪个API，导入语句工作得非常好（是的，可以使用限定类名绕过导入语句，但很少有人这样做，因为这会使源代码很难读取）。或者，只需从类路径中移除库，并查看编译错误发生的位置。

我建议不要在javadoc中记录这一点，因为你的类的调用者应该不知道它的实现。也就是说，我认为API以前是调用者不应该知道的实现细节 - 调用者不应该知道的内容不应与他必须知道的事情混在一起。

Answer 2

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

只是在描述中的某处（个人）最好提到它。不要为这样的事情定义自定义标签，这是不值得的麻烦。重要的是（如果有必要）信息在那里。这样做没有固定的惯例。

我故意说“如果有必要” - 大部分时间我都会说这不是必需的。然而，如果处理一个并不广为人知的图书馆，而不是Maven和/或有在发布之间做出突破性改变的倾向，那么至少在某处可以证明这是值得记录的。