usar - para que sirve @param java

JavaDoc para métodos privados/protegidos?

Question

¿Debo escribir JavaDoc para métodos privados o protegidos ? ¿Y qué pasa con las variables privadas ?

Veo ejemplos de clase en mi libro de Java y las variables privadas son JavaDoc''ed. Así que no puedo entender si es una buena práctica JavaDoc los métodos privados (o protegidos ).

Answer 1

A menudo escuchas la recomendación general de que, en el mejor de los casos, los comentarios simplemente no deberían ser necesarios . Pero en lo que respecta a JavaDoc, juegan un papel importante no solo para el desarrollador, sino también para el usuario de la biblioteca.

Además, escribir comentarios de JavaDoc puede ser más útil para ti (especialmente para un principiante) que para cualquier otra persona: cuando te resulta difícil describir qué es una variable o qué hace un método con un solo /** One-line-JavaDoc comment */ una sola /** One-line-JavaDoc comment */ , entonces automáticamente volverás a pensar lo que has hecho allí.

Al generar JavaDocs, puede elegir si desea generarlos solo para las partes public y protected de la API, o también para elementos predeterminados o private .

Sin embargo, en cualquier caso, debe documentar protected métodos protected : ¿Puede alguien que amplíe la clase llamar solo a este método o se le permite anular este método? Si es así, ¿hay alguna condición previa y posterior que deba conocer? ¿Debería llamar a super.theMethod() en la versión reemplazada? (Por cierto: si no se le permite anular el método, entonces debe ser final , pero documentado de todos modos)

Por cierto: personalmente comento todo , pero sé que la mayoría de la gente piensa que no es necesario o incluso un mal estilo, especialmente para cosas "triviales"

/**
 * The number of elements in this set
 */
private final int numberOfElements;

Creo que no daña, pero ayuda en muchos casos. Tal vez, con respecto a private partes private , es solo una cuestión de gusto.

Answer 2

La primera pregunta que debes hacerte es "¿por qué escribir JavaDocs?" Para quiénes son útiles? ¿Quién te pidió que las escribieras?

Lo más probable es que alguien (empleador / profesor) le pida que documente algunos de sus métodos. Esto generalmente es algo bueno, pero tiene un costo: mantenimiento adicional.

Si tiene una versión de acceso público de sus documentos (como si los está generando y publicándolos en línea para los usuarios finales), tiene sentido documentar todo lo que sus usuarios finales necesitarán saber. Esto incluye todas las clases y métodos públicos.

¿Qué hay de ti y de otros desarrolladores?

Mi opinión es que no debes usar javadocs en métodos y clases internas y privadas. La razón principal es que los javadocs benefician principalmente a las personas que consumen, no mantienen, su código.

Por otro lado, necesitas mantener notas y comentarios en tu propio código, que a menudo es interno. En este caso, sugeriría comentarios normales (ej. // ); es menos mantenimiento, y a menudo, igualmente claro, con mucho menos tipeo.

Por otro lado, si un método se vuelve público, puede ser útil convertir esos comentarios en un verdadero javadocs. Los Javadoc tienen la ventaja de obligarlo a pensar (y documentar) cada parámetro, excepción y valor de retorno.

El compromiso es tuyo para hacer.

Answer 3

No tiene que javadoc nada, pero es muy útil. Más javadocs nunca son algo malo.

Según su pregunta, si utiliza el compilador de documentación javadoc, javadocs se compilará para métodos protegidos, pero no para métodos privados. Sin embargo, no hay ninguna razón por la que todavía no puedan usarse como comentarios de código.

Answer 4

No, no deberías escribir javadoc para métodos privados. Los usuarios finales no tienen acceso a campos o métodos privados, por lo que realmente no tiene sentido proporcionarles javadoc. Los campos y métodos privados solo están destinados al desarrollador. Sin embargo, si realmente lo necesita, siéntase libre de escribir comentarios para una lógica no obvia. Probablemente deberías escribir javadoc para protected métodos protected porque estos métodos a veces se anulan y es útil proporcionar al usuario cierta información sobre lo que el método hace o debería hacer.

Answer 5

Sí, debe escribir JavaDoc para métodos privados, e incluso cuando sea solo para usted. En 3 años, cuando tenga que cambiar el código, le complacerá que lo haya documentado.

Si se va de la empresa o tiene que trabajar en otro proyecto, sus compañeros estarán felices de tener un código documentado. El código no documentado tiene un valor mucho menor.

Y mira cómo lo hacen los verdaderos profesionales. Aquí hay un extracto del código fuente de la clase ArrayList de Sun Microsystems :

 /**
  * The array buffer into which the elements of the ArrayList are stored.
  * The capacity of the ArrayList is the length of this array buffer.
  */
  private transient Object[] elementData;