在代码中处理/格式化 Javadoc 和注释的最佳方法是什么？ [复制]答案

【问题标题】：What's the best way to handle/format Javadoc and annotations in code? [duplicate]在代码中处理/格式化 Javadoc 和注释的最佳方法是什么？ [复制]
【发布时间】：2011-10-22 10:27:28
【问题描述】：

我浏览了这个论坛，并在谷歌上搜索了这个论坛，但我不确定处理 Javadoc 和同一类中一起出现的注释的最佳方法是什么。

从我从 Sun/Oracle 的文档中可以看到，他们似乎建议（虽然我找不到明确的声明）Javadoc 应该列在注释之上。

查看他们的示例How and When to Deprecate API's。

这对于像@Deprecated 或@Override 这样简单的东西非常有用。但是如果你使用 JPA 和/或 Hibernate 呢？您的类和方法肯定会被大量注释（有时每个类或方法有两个或更多注释）。

我猜 Javadoc 还在注解之上？

我还想知道如何最好地使用注释？我已经看到了一些示例，其中注释“堆叠”在类、成员、方法之上。而且我见过其他人在同一行列出注释（通常是这里的方法）。

哪个最好？哪个更易读？

您是否“记录”了您在 Javadoc 中注释某些内容的事实？

我正在寻找关于这方面的一套好的文档和/或您自己关于什么是最易读/可维护的经验。

【问题讨论】：

您不需要明确提及您添加了注释；具有@Documented 注释的注释会自动添加到文档中。

标签： java formatting annotations javadoc code-documentation

【解决方案1】：

我认为您混淆了代码注释和 javadoc 注释。

javadoc cmets 就是这样：cmets。 /** */ 实际包含的内容对您的应用程序无关紧要（当然，除非您生成 javadoc）

代码注释实际上会影响应用程序的功能。如果您省略注释（并且不提供休眠配置文件），您的休眠映射类将不起作用。仅在 javadoc 注释中而不在代码中标记为 @Deprecated 的方法不会被编译器识别为已弃用。（在这种情况下，javadoc 工具可能会警告您）

所以，是的，代码和 javadoc 中的注释具有相同的名称，但它们完全不同。对于@Deprecated，您应该同时使用：在代码中将它们标记为已弃用，并记录原因。

【讨论】：

不，我没有混合它们。我在问什么是“在代码中”格式化它们以使代码可读的最佳方法。从技术上讲，您可以先列出注释，然后是 javadoc，然后是源代码……尽管我不确定为什么。我从代码可读性的角度询问更多。
ok ... 个人认为注解属于代码：javadoc - annotations - source

【解决方案2】：

Javadoc 仅用于记录类、方法等。注解可以更改给定代码的功能（例如来自 Hibernate 或 Spring 的注解）。所以，对我来说，很明显注解应该更接近代码（所以，在 javadoc 和方法/函数之间）。

但是如何写注解，哪里有很多呢？这取决于，我更喜欢将它们分开放置，如果有短线并以某种方式连接，则很少有例外。

我认为在 Javadoc 中显式记录您正在使用注释并不是一个好主意。注释本身可以有@Documented 注释，说明它们应该出现在生成的javadocs 中。除此之外，它是实现细节 - javadoc 应该说明为什么方法/对象制作，而不是你是如何做的（主要是，至少）。

【讨论】：