代码风格；将javadoc放在注释之前还是之后？答案

【问题标题】：codestyle; put javadoc before or after annotation?代码风格；将javadoc放在注释之前还是之后？
【发布时间】：2011-03-07 19:12:33
【问题描述】：

我知道这不是最重要的问题，但我刚刚意识到我可以将 javadoc 注释块放在注释之前或之后。我们希望采用什么作为编码标准？

/**
 * This is a javadoc comment before the annotation 
 */
@Component
public class MyClass {

    @Autowired
    /**
     * This is a javadoc comment after the annotation
     */
    private MyOtherClass other;
}

【问题讨论】：

标签： java coding-style annotations javadoc code-documentation

【解决方案1】：

除了编码标准之外，如果 javadoc cmets 放在注释之后，javadoc 工具似乎不会处理它们。否则工作正常。

【讨论】：

【解决方案2】：

我同意以上所有内容。在使用 RestEasy 样式时，IntelliJ (Idea) 的代码样式模板可能会在误报（正确指定 @throws 时发出警告）和误报（当未指定 @throws 时，但应该如此）失败，这可能对其他人有所帮助注释。我把我的 javadocs 放在一切之上，然后是注释，然后是代码。

在此处查看错误报告： https://youtrack.jetbrains.com/issue/IDEA-220520

【讨论】：

【解决方案3】：

在注解之前，因为注解是“属于”类的代码。请参阅官方文档中的examples with javadoc。

这是我在another official Java page 中找到的随机示例：

/**
 * Delete multiple items from the list.
 *
 * @deprecated  Not for public use.
 *    This method is expected to be retained only as a package
 *    private method.  Replaced by
 *    {@link #remove(int)} and {@link #removeAll()}
 */
@Deprecated public synchronized void delItems(int start, int end) {
    ...
}

【讨论】：

这里也很有趣 - 注释与方法的其他限定符位于同一行。我以前从未见过这样做过，但它似乎表明应该像对待方法的其他限定符一样对待注释，因此，javadoc 绝对应该放在它之前。
如果您使用的是像 Jackson 这样的大量注释，那么将相同的注释放在同一行上会很快失控。我将每个注释放在自己的一行上。

【解决方案4】：

我同意已经给出的答案。

注释是代码的一部分，而javadoc是文档的一部分（因此得名）。

所以对我来说，将代码部分放在一起是合理的。

【讨论】：

【解决方案5】：

这一切都归结为可读性。在我看来，使用方法/字段正上方的注解代码更具可读性。

【讨论】：

特别是如果 javadoc 真的很长！