estilo de código poner javadoc antes o después de la anotación?

184

Sé que no es el más importante de los problemas, pero me di cuenta de que puedo poner el bloque de comentarios javadoc antes o después de la anotación. ¿Qué nos gustaría adoptar como estándar de codificación?

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

Respuestas:

191

Antes de la anotación, ya que la anotación es un código que "pertenece" a la clase. Vea ejemplos con javadoc en la documentación oficial.

Aquí hay un ejemplo aleatorio que encontré en otra página oficial de 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
fuente
8
También es interesante aquí: la anotación está en la misma línea que los otros calificadores para el método. Nunca lo había visto antes, pero parece sugerir que las anotaciones deben tratarse de manera similar a otros calificadores para un método, y como tal, el javadoc definitivamente debería ir antes.
ArtOfWarfare
8
Poner las mismas anotaciones en la misma línea puede salirse rápidamente de control si está usando algo pesado como Jackson. Puse cada anotación en una línea propia.
WW.
17

Estoy de acuerdo con las respuestas ya dadas.

Las anotaciones son parte del código, mientras que javadoc es parte de la documentación (de ahí el nombre).

Entonces, para mí parece razonable mantener juntas las partes del código.

perdian
fuente
11

Todo se reduce a legibilidad. En mi opinión, el código es más legible con las Anotaciones directamente sobre el método / campo.

Estanque Robby
fuente
11

Aparte del estándar de codificación, parece que la herramienta javadoc no procesa los comentarios de javadoc si se colocan después de las anotaciones. Funciona bien de lo contrario.

shadrik
fuente
0

Estoy de acuerdo con todo lo anterior. Puede ser útil para otros que las plantillas de estilo de código de IntelliJ (Idea) fallen falsamente positivas (cuando @throws se especifica correctamente, advierte) y falsamente negativas (cuando @throws no se especifica, pero deberían serlo) cuando se usa el estilo RestEasy anotaciones Puse mis javadocs por encima de todo lo demás, luego anotaciones, luego código.

Vea el informe de error aquí: https://youtrack.jetbrains.com/issue/IDEA-220520

Max P Magee
fuente