He refactorizado una clase y movido un poco de código desde el constructor a un inicializador estático. ¿Qué debería hacer con el javadoc que estaba en el constructor? ¿Es posible agregar javadoc a un inicializador estático?¿Cómo puedo agregar javadoc a un inicializador estático en Java?
En primer lugar, es discutible si los inicializadores estáticos son una buena práctica para empezar.
Si decide utilizarlos de todos modos, agregaría la documentación al JavaDoc en el nivel de clase. Los inicializadores estáticos pueden, dependiendo de cómo se implementen, causar efectos secundarios. Si usa inicializadores estáticos con efectos secundarios, el comportamiento debe documentarse para el consumidor de dicha clase.
JavaDoc está destinado principalmente a documentar la interfaz de la clase. Los comentarios de JavaDoc deben preceder a una declaración de clase, campo, constructor o método.
Un inicializador estático no es parte de la interfaz. Es parte de la implementación de la clase.
Puede documentar su comportamiento en la documentación de la clase, si lo desea.
El inicializador estático de una clase puede tener efectos secundarios que valen la pena documentar. Aunque es discutible si los inicializadores estáticos son una buena práctica para empezar. – Waldheinz
¿Los métodos privados y los campos son parte de su interfaz? – tttppp
@tttppp Son 'privados' y, por lo tanto, no forman parte de la interfaz. – Waldheinz
yo diría que las partes importantes de la documentación que se debe mover a la documentación de la clase:
/**
* Your text here.
*/
public class SomeClass {
static {
/* your static initalizer */
}
}
No existe un constructor estático en Java (as oposed to C#), por lo que debe documentar este comportamiento en el nivel de clase.
Además, dado que el inicializador estático probablemente inicialice algunos campos estáticos, si estos campos son públicos, protegidos (o paquetes privados, según su convención de visibilidad JavaDoc), debe agregar detalles sobre la forma en que estos campos son inicializado basado en el comportamiento del inicializador estático.
+1 por "efectos secundarios desagradables" – Waldheinz