Codestyle; put javadoc before or after annotation?

java

javadoc

best-practices

coding-style

byAlex Kataev·Jan 27, 2025

Directly above the method or class, place JavaDoc comments outlining the purpose, parameters, and return values, followed by the respective annotations. By doing this, you improve readability by clearly associating commentary with the code components it describes.

/**
 * Executes an action.
 * @param input Description.
 * @return Description.
 */
@Annotation
public Result action(Input input) {
    // Implementation details go here.
    // Spoiler: It involves a bit of magic and a unicorn 🦄.
}

In essence, use JavaDoc as your code’s introductory statement and annotations immediately before the code to provide metadata or behavior.

Justification for putting JavaDoc first

Placing JavaDoc comments before annotations doesn't simply adhere to style guides, but it is a prerequisite for the Java documentation process. The JavaDoc tool expects JavaDoc comments to immediately precede Java elements they document. If you place annotations before JavaDocs, it could influence the tool's ability to correctly generate corresponding HTML documentation. Or to put it in more practical terms, it's like putting a punchline before the joke, now - that doesn't make sense, does it?

Aim for uniformity in code

Keeping a consistent coding style across your entire project simplifies maintenance and makes code reviews a walk in the park. With a consistent format, scanning for documentation, metadata, and behavioral overview in the code becomes almost second nature. Homogeneity is crucial, especially when you're knee-deep in hundreds of classes or when working with teams bigger than a hobbit's fellowship.

Exceptions to the rule

No rule is complete without its exceptions. So, are there instances when annotations come before JavaDoc? Yes, a few. For one, when using package-level annotations in a package-info.java file, the annotation comes before the JavaDoc comment as it applies to the entire package, not an individual Java element.

Coping with IDE template glitches

Your IDE might cause some friction here. Some IDEs, specifically IntelliJ IDEA Code Style templates might demonstrate a rather rebellious behavior, putting annotations before Javadocs. One solution can be to pester the guys maintaining the IDE by raising an issue on their tracker. You can also take matters into your own daunting hands and adjust the IDEs code style settings to better match the official recommendations.

Practical examples and edge cases

In the grand scheme of things, a few practical examples illustrate the value of well-positioned JavaDocs and annotations rather aptly. The following examples also ensure that your code never falls victim to fashion faux pas.

Example 1: Method documentation

/**
 * Crisp addition method that returns a sum so precise that Pythagoras would be proud.
 * @param a the first operand
 * @param b the second operand
 * @return the total of the two operands
 */
@CustomAnnotation
public int add(int a, int b) {
    // Who said addition cannot be fun? 
    return a + b;
}

Example 2: Class-level annotations

/**
 * This craftily designed class presents a system user with credentials.
 */
@Entity
@Table(name = "users")
public class User {
    
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;
    
    // Other fields and methods go here...
    // Spoiler: They go on a coffee break every Friday afternoon.
}

In this example, the JavaDoc gives a brief of what the class is about, while the annotations dictate the ORM mappings.

Example 3: Overridden methods

In situations where a method is overriden, a JavaDoc still remains necessary, especially when the functionality has changed from the initial definition:

@Override
/**
 * A generous sprinkle of customization to handle edge cases.
 */
@CustomAnnotation
public void performAction() {
    // You know best, do your things here!
}

Official guides and conventions

Besides what your personal or team preferences might be, there are authoritative guides and official references to address these practices:

The Oracle Java Documentation: Advocates the doctrine of JavaDoc before annotations.
Google Java Style Guide: Considers annotations in its styling guide.
Renowned books on Java (citing Effective Java here) give valuable inputs in terms of widely acceptable coding practices.