代码风格；将 javadoc 放在注释之前还是之后？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/3109950/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
codestyle; put javadoc before or after annotation?
提问by Paul McKenzie
I know that it isn't the most vital of issues, but I just realised that I can put the javadoc comment block before or after the annotation. What would we want to adopt as a coding standard?
我知道这不是最重要的问题，但我刚刚意识到我可以在注释之前或之后放置 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;
}
采纳答案by Peter Jaric
Before the annotation, since the annotation is code that "belongs" to the class. See examples with javadocin the official documentation.
在注解之前，因为注解是“属于”类的代码。请参阅官方文档中带有 javadoc 的示例。
Here's random example I found in another official Java page:
这是我在另一个官方 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) {
...
}
回答by Robby Pond
It all comes down to readablity. In my opinion code is more readable with the Annotations directly above the method/field.
这一切都归结为可读性。在我看来，使用方法/字段正上方的注释，代码更具可读性。
回答by perdian
I agree with the answers already given.
我同意已经给出的答案。
Annotations are part of the codewhile javadoc is part of the documentation(hence the name).
注释是代码的一部分，而 javadoc 是文档的一部分（因此得名）。
So for me it seams reasonable to keep the code parts together.
所以对我来说，将代码部分保持在一起是合理的。
回答by shadrik
Aside from the coding standard, it seems that javadoc tool doesn't process the javadoc comments if they are placed after the annotations. Works fine otherwise.
除了编码标准之外，如果将 javadoc 注释放在注释之后，javadoc 工具似乎不会处理它们。否则工作正常。
回答by Max P Magee
I agree with all of the above. It may be helpful to others that IntelliJ (Idea)'s code style templates fail both falsely positive (when @throws is specified correctly, it warns) and falsely negative (when @throws is not specified, but should be) when using RestEasy style annotations. I put my javadocs above everything else, then annotations, then code.
我同意以上所有内容。IntelliJ (Idea) 的代码样式模板在使用 RestEasy 样式时会出现误报（当正确指定 @throws 时，它会发出警告）和误报（当未指定 @throws 时，但应该是）失败时，这可能对其他人有帮助注释。我把我的 javadoc 放在一切之上，然后是注释，然后是代码。
See the bug report here: https://youtrack.jetbrains.com/issue/IDEA-220520
在此处查看错误报告：https: //youtrack.jetbrains.com/issue/IDEA-220520
