codestilo; colocar javadoc antes ou depois da anotação?

184

Sei que não é o problema mais importante, mas acabei de perceber que posso colocar o bloco de comentários javadoc antes ou depois da anotação. O que gostaríamos de adotar como um padrão de codificação?

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

    @Autowired
    /**
     * This is a javadoc comment after the annotation
     */
    private MyOtherClass other;
}
java coding-style annotations javadoc code-documentation Paul McKenzie
fonte

Respostas:

191

Antes da anotação, uma vez que a anotação é um código que "pertence" à classe. Veja exemplos com javadoc na documentação oficial.

Aqui está um exemplo aleatório que encontrei em outra página oficial do 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
Também é interessante aqui - a anotação está na mesma linha que os outros qualificadores para o método. Eu nunca vi isso antes, mas parece sugerir que as anotações devem ser tratadas como outros qualificadores para um método e, como tal, o javadoc definitivamente deve ir adiante.
ArtOfWarfare 6/11
8
Colocar as mesmas anotações na mesma linha pode rapidamente ficar fora de controle se você estiver usando algo pesado como anotações, como Jackson. Coloquei cada anotação em uma linha própria.
WW.
17

Eu concordo com as respostas já dadas.

As anotações fazem parte do código, enquanto o javadoc faz parte da documentação (daí o nome).

Então, para mim, parece razoável manter as partes do código juntas.

perdian
fonte
11

Tudo se resume à legibilidade. Na minha opinião, o código é mais legível com as anotações diretamente acima do método / campo.

Robby Pond
fonte
11

Além do padrão de codificação, parece que a ferramenta javadoc não processa os comentários do javadoc se eles forem colocados após as anotações. Funciona bem caso contrário.

shadrik
fonte
0

Eu concordo com todos os itens acima. Pode ser útil para outras pessoas que os modelos de estilo de código do IntelliJ (Idea) falhem tanto falsamente positivos (quando @throws for especificado corretamente, ele avisa) quanto falsamente negativos (quando @throws não for especificado, mas deve ser) ao usar o estilo RestEasy anotações. Coloquei meus javadocs acima de tudo, anotações e código.

Veja o relatório de erros aqui: https://youtrack.jetbrains.com/issue/IDEA-220520

Max P Magee
fonte