codestyle; mettre javadoc avant ou après l'annotation?

187

Je sais que ce n'est pas le problème le plus vital, mais je viens de réaliser que je peux mettre le bloc de commentaires javadoc avant ou après l'annotation. Que voudrions-nous adopter comme norme de codage?

/**
 * This is a javadoc comment before the annotation 
 */
@Component
public class MyClass {

    @Autowired
    /**
     * This is a javadoc comment after the annotation
     */
    private MyOtherClass other;
}

— Paul McKenzie
source

194

Avant l'annotation, puisque l'annotation est un code qui "appartient" à la classe. Voir des exemples avec javadoc dans la documentation officielle.

Voici un exemple aléatoire que j'ai trouvé dans une autre page officielle 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) {
    ...
}

— Peter Jaric
source

8

Aussi intéressant ici - l'annotation est sur la même ligne que les autres qualificatifs de la méthode. Je n'ai jamais vu cela faire auparavant, mais cela semble suggérer que les annotations devraient être traitées comme les autres qualificatifs pour une méthode, et en tant que tel, le javadoc devrait définitivement aller avant.

— ArtOfWarfare

8

Mettre les mêmes annotations sur la même ligne peut rapidement devenir incontrôlable si vous utilisez quelque chose de lourd comme Jackson. Je mets chaque annotation sur une ligne qui lui est propre.

— WW.

17

Je suis d'accord avec les réponses déjà données.

Les annotations font partie du code tandis que javadoc fait partie de la documentation (d'où le nom).

Donc, pour moi, il semble raisonnable de garder les parties de code ensemble.

— perdian
source

11

Tout se résume à la lisibilité. À mon avis, le code est plus lisible avec les annotations directement au-dessus de la méthode / du champ.

— Robby Pond
source

11

Mis à part la norme de codage, il semble que l'outil javadoc ne traite pas les commentaires javadoc s'ils sont placés après les annotations. Fonctionne bien autrement.

— shadrik
source

0

Je suis d'accord avec tout ce qui précède. Il peut être utile aux autres que les modèles de style de code d'IntelliJ (Idea) échouent à la fois faussement positifs (lorsque @throws est spécifié correctement, il avertit) et faussement négatifs (lorsque @throws n'est pas spécifié, mais devrait l'être) lors de l'utilisation du style RestEasy annotations. Je place mes javadocs avant tout, puis les annotations, puis le code.

Voir le rapport de bogue ici: https://youtrack.jetbrains.com/issue/IDEA-220520

— Max P Magee
source