codestyle; put javadoc before or after annotation?

JavaCoding StyleAnnotationsJavadocCode Documentation

Java Problem Overview


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?

/**
 * 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 Solutions


Solution 1 - Java

Before the annotation, since the annotation is code that "belongs" to the class. See examples with javadoc in the official documentation.

Here's random example I found in 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) {
    ...
}

Solution 2 - Java

I agree with the answers already given.

Annotations are part of the code while javadoc is part of the documentation (hence the name).

So for me it seams reasonable to keep the code parts together.

Solution 3 - Java

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.

Solution 4 - Java

It all comes down to readablity. In my opinion code is more readable with the Annotations directly above the method/field.

Solution 5 - Java

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.

See the bug report here: https://youtrack.jetbrains.com/issue/IDEA-220520

Attributions

All content for this solution is sourced from the original question on Stackoverflow.

The content on this page is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

Content TypeOriginal AuthorOriginal Content on Stackoverflow
QuestionPaul McKenzieView Question on Stackoverflow
Solution 1 - JavaPeter JaricView Answer on Stackoverflow
Solution 2 - JavaChristian SeifertView Answer on Stackoverflow
Solution 3 - JavashadrikView Answer on Stackoverflow
Solution 4 - JavaRobby PondView Answer on Stackoverflow
Solution 5 - JavaMax P MageeView Answer on Stackoverflow