代码风格；在注释之前或之后放置javadoc？

183

我知道这不是最重要的问题，但是我刚刚意识到我可以将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;
}

— 保罗·麦肯齐
source

191

在注释之前，由于注释是“属于”该类的代码。请参阅官方文档中带有Javadoc的示例。

这是我在另一个官方Java页面上发现的随机示例：

/**
 * 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) {
    ...
}

— 彼得·贾里克
source

8

这里也很有趣-注释与该方法的其他限定符在同一行。我以前从未见过这样做，但似乎建议应将注解与方法的其他限定符一样对待，因此，javadoc绝对应优先于此。

— ArtOfWarfare 2013年

8

如果您使用大量的注释（如Jackson），则将相同的注释放在同一行上会很快失去控制。我将每个注释放在自己的一行上。

— WW。

17

我同意已经给出的答案。

批注是代码的一部分，而javadoc是文档的一部分（因此为名称）。

因此，对我来说，将代码部分保持在一起是合理的。

— 波斯人
source

11

一切都归结为可读性。我认为，使用方法/字段正上方的注释更易于阅读代码。

— 罗比池塘
source

11

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

— 沙德里克
source

0

我同意以上所有观点。使用RestEasy样式时，IntelliJ（Idea）的代码样式模板可能会误判为假（当正确地指定@throws时，它会警告）和误判会的错误（当未指定@throws时，但应该是）。注释。我将javadocs放在所有其他内容之上，然后是注释，然后是代码。

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

— 马克斯·马吉
source