codestyle; mettere javadoc prima o dopo l'annotazione?

184

So che non è il problema più vitale, ma mi sono appena reso conto che posso inserire il blocco di commenti javadoc prima o dopo l'annotazione. Cosa vorremmo adottare come standard di codifica?

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

191

Prima dell'annotazione, poiché l'annotazione è un codice che "appartiene" alla classe. Vedi esempi con javadoc nella documentazione ufficiale.

Ecco un esempio casuale che ho trovato in un'altra pagina ufficiale di 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
fonte

8

Anche qui di interesse: l'annotazione si trova sulla stessa riga degli altri qualificatori per il metodo. Non l'ho mai visto prima, ma sembra suggerire che le annotazioni debbano essere trattate in modo molto simile ad altri qualificatori per un metodo, e come tale, il javadoc dovrebbe assolutamente andare prima di esso.

— ArtOfWarfare il

8

Mettere le stesse annotazioni sulla stessa riga può sfuggire rapidamente se si utilizza qualcosa di pesante come annotazioni come Jackson. Metto ogni annotazione su una riga a parte.

— WW.

17

Sono d'accordo con le risposte già fornite.

Le annotazioni fanno parte del codice mentre javadoc fa parte della documentazione (da cui il nome).

Quindi per me è ragionevole tenere insieme le parti del codice.

— perdian
fonte

11

Tutto si riduce alla leggibilità. Secondo me il codice è più leggibile con le annotazioni direttamente sopra il metodo / campo.

— Robby Pond
fonte

11

A parte lo standard di codifica, sembra che lo strumento javadoc non elabori i commenti javadoc se vengono inseriti dopo le annotazioni. Funziona bene altrimenti.

— shadrik
fonte

0

Sono d'accordo con tutto quanto sopra. Può essere utile per gli altri che i modelli di stile di codice di IntelliJ (Idea) falliscano sia falsamente positivi (quando @throws è specificato correttamente, avvisa) sia falsamente negativi (quando @throws non è specificato, ma dovrebbero esserlo) quando si usa lo stile RestEasy annotazioni. Metto i miei javadocs sopra ogni altra cosa, quindi annotazioni, quindi codice.

Vedi la segnalazione di bug qui: https://youtrack.jetbrains.com/issue/IDEA-220520

— Max P Magee
fonte