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;
}

— Paul McKenzie
fonte

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