codestyle; put javadoc before or after annotation?

Question

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;
}

score 230 · Accepted Answer · edited Sep 13 '22 at 08:41

230

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

Here's a 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) {
    ...
}

edited Sep 13 '22 at 08:41

banan3'14

3,810
3
24
47

answered Jun 24 '10 at 12:37

Peter Jaric

5,162
3
30
42

9

Also of interest here - the annotation is on the same line as the other qualifiers for the method. I've never seen that done before, but it seems to suggest that annotations should be treated much like other qualifiers for a method, and as such, the javadoc should definitely go before it. – ArtOfWarfare Nov 06 '13 at 18:42
9

Putting the same annotations on the same line can quickly get out of hand if you are using something annotation-heavy like Jackson. I put each annotation on a line of it's own. – WW. Apr 10 '15 at 02:43

score 20 · Answer 2 · answered Jun 24 '10 at 13:05

20

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.

answered Jun 24 '10 at 13:05

Christian Seifert

2,780
5
29
45

score 17 · Answer 3 · edited Jan 01 '20 at 01:44

17

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.

edited Jan 01 '20 at 01:44

Tsunoba

60
6

answered Oct 25 '13 at 08:49

shadrik

349
1
4
10

score 13 · Answer 4 · answered Jun 24 '10 at 12:38

13

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

answered Jun 24 '10 at 12:38

Robby Pond

73,164
16
126
119

Especially if the javadoc was really long! – 700 Software Sep 03 '21 at 20:41
Well, IMHO it's better if the docs are above, so you can skip them all together and read the code. Furthermore IDEs can compact the javadocs. My two cents. – Marco Sulla Jan 27 '23 at 11:30

score 0 · Answer 5 · answered Aug 12 '19 at 17:38

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

codestyle; put javadoc before or after annotation?

5 Answers5

Linked

Related