web-dev-qa-db-fra.com

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

Je sais que ce n'est pas le plus vital des problèmes, 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;
}
javacoding-styleannotationsjavadoccode-documentation
173
Paul McKenzie

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

Voici un exemple aléatoire que j'ai trouvé dans n autre officiel 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) {
    ...
}
185
Peter Jaric

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

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

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

16
perdian

En dehors de la norme de codage, il semble que l'outil javadoc ne traite pas les commentaires doc Java s'ils sont placés après les annotations. Fonctionne bien sinon.

11
shadrik

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.

10
Robby Pond

Je suis d'accord avec tout ce qui précède. Il peut être utile pour d'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 mets mes javadocs au-dessus de tout le reste, puis des annotations, puis du code.

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

0
Max P Magee