¿JavaDoc para métodos privados/protegidos? [closed]

9 minutos de lectura

avatar de usuario de smartmouse
ratón inteligente

¿Debo escribir JavaDoc para privado o protegido ¿métodos? Y que hay con privado variables?

Veo ejemplos de clases en mi libro de Java y el privado las variables son JavaDoc’ed. Así que no puedo entender si es una buena práctica para JavaDoc el privado (o protegido) métodos.

  • Debes escribir comentarios para cualquier cosa que no sea obvia.

    – SLaks

    07/02/2014 a las 15:50

  • En sus javadocs en métodos privados/protegidos aparecerá si usa el comando show javadocs en su IDE (al menos Intellij). Los comentarios en línea no lo harán. Ese es un beneficio práctico para los javadocs en lugar de los comentarios en línea cuando la descripción más allá de la firma del método es útil.

    – CorayThan

    21 de febrero de 2017 a las 18:26

Avatar de usuario de AlexWien
AlexWien

Sí, debe escribir JavaDoc para métodos privados, e incluso cuando es solo para usted. En 3 años, cuando tenga que cambiar el código, estará feliz de haberlo documentado.

Si deja la empresa o tiene que trabajar en otro proyecto, sus compañeros de trabajo estarán encantados 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 Lista de arreglo clase por microsistemas de sol:

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

  • ¿El público HelloWorld() {system.out.println(“Hello World”)} tiene menos valor que //imprime Hello World HelloWorld() {system.out.println(“Hello World”)}?

    – cbelsole

    10 de julio de 2014 a las 16:52


  • No hablamos de una línea muy conocida Hola mundo coede. En el desarrollo profesional, el código sin documentar genera mayores costos para la próxima persona que trabaje en ese código. E incluso si es tu propio código, algunos años después de crearlo, pierdes más tiempo pensando por qué y qué, que los costos de documentación en el momento de la creación vuelan.

    – AlexWien

    10/07/2014 a las 18:45


  • La pregunta claramente es sobre JAVADOC. Como dice la respuesta de ashes999, Javadoc es principalmente para las personas que consumen su código. Estás hablando de COMENTAR tu código y lo que estás diciendo es válido y estoy en el mismo camino, pero esto no cuenta para javadoc. Javadoc no está diseñado para guardar sus comentarios para usted y sus compañeros de trabajo y hacerlos públicos para todos sus consumidores.

    – usuario de prueba

    20 de octubre de 2014 a las 8:06

  • @testuser a su comentario: “javadoc no está diseñado para mantener sus comentarios …” Javadoc tiene una característica que le permite crear el javadoc html solo para métodos/campos públicos. Así que escriba lo privado para usted y publique solo los públicos para los consumidores, si hay alguna necesidad de suprimir información.

    – AlexWien

    20/10/2014 a las 18:22


  • @AlexWien: ese es un punto válido, pero ¿cuál es la ventaja de convertirlo en comentarios de Javadoc? ¿Por qué no simplemente mantenerlo como comentarios ‘simples’? Javadoc es en mi humilde opinión (un poco, pero aún) más trabajo. Y para generar solo la parte del HTML público, supongo que requiere una configuración adicional, por lo tanto, tiempo adicional invertido, mientras que simplemente podría agregarlo como comentarios ‘normales’ en su lugar.

    – usuario de prueba

    21/10/2014 a las 12:45

La primera pregunta que debe hacerse es “¿por qué escribir JavaDocs?” ¿Para quién son útiles? ¿Quién te pidió que las escribieras?

Lo más probable es que alguien (empleador/profesor) le haya pedido 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 (por ejemplo, si los está generando y publicando en línea para los usuarios finales), tiene sentido documentar cualquier cosa sus usuarios finales necesitarán saberlo. Esto incluye todas las clases y métodos públicos.

¿Qué pasa contigo y con otros desarrolladores?

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

Por otro lado, es necesario que mantenga notas y comentarios en su propio código, que a menudo es interno. En este caso, sugeriría comentarios normales (p. //) en cambio; 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 javadoc. Los Javadocs tienen la ventaja de obligarlo a pensar (y documentar) cada parámetro, excepción y valor de retorno.

La compensación es suya para hacer.

  • Para su información, para los desarrolladores de .NET, Visual Studio muestra estos comentarios cuando pasa el mouse sobre el nombre de un método, incluso para métodos privados, por lo que para el código de .NET, tiene sentido hacer esto.

    – cenizas999

    20 de octubre de 2014 a las 13:58

  • Eclipse hace lo mismo, es una característica muy beneficiosa.

    – Davor

    13 de noviembre de 2014 a las 12:41

  • No veo por qué “//” requiere menos mantenimiento que “/**”. Y prácticamente usar “//” es más escribir, porque eclipse generaría el tremplate de javadoc automáticamente para usted.

    – AlexWien

    24/04/2015 a las 16:54

  • AFAIK eclipse, visual studio, netbeans e intellij pueden mostrar javadoc de manera muy conveniente, por lo que, en mi opinión, es beneficioso para todos los que trabajan con su código.

    – Pieter De Bié

    29 de marzo de 2016 a las 14:01

  • @kidburla Escribiría comentarios de javadoc para protected métodos porque cuando estos se reemplazan, se heredarán. Y también si está desarrollando una aplicación de plataforma que otros desarrolladores construirán sobre ella, guarda los comentarios de reescritura de Java doc. Si el comportamiento de los métodos anulados cambia y será utilizado públicamente, deberán escribir una versión revisada de los comentarios de javadoc.

    – David

    27 de febrero de 2017 a las 10:31

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 porque estos métodos a veces se anulan y es útil proporcionar al usuario información sobre lo que hace o debería hacer el método.

  • ¿Y qué pasa con las variables?

    – ratón inteligente

    7 febrero 2014 a las 15:56

  • No deberías usar campos privados de javadoc, pero eres bienvenido a javadoc protected campos porque a menudo tienen alguna importancia en cuanto a por qué son protected Opuesto a private. Todavía puede proporcionar líneas de comentarios en cualquier lugar, ya sea que describa el propósito de una variable o la lógica en un método.

    – Josh M.

    7 febrero 2014 a las 15:58


  • Si proporciona una línea de comentario para un método o campo privado, es mejor que escriba un javadoc, esto no tiene desventajas, solo ventajas.

    – AlexWien

    7 febrero 2014 a las 16:09

  • @AlexWien No estoy en desacuerdo con su respuesta, pero ¿para qué sirve escribir javadoc para miembros privados en lugar de comentarios? Los miembros son privados para evitar que el usuario acceda a ellos directamente (a pesar de la reflexión). Si tiene miembros privados de javadoc, ¿no está facilitando al usuario final la ingeniería inversa del programa?

    – Josh M.

    7 febrero 2014 a las 16:13

  • escribir javadoc no significa presentarlo al usuario final. javadoc para un método privado proporciona una estructura sobre cómo comentar (internamente). Exige comentar todos los parámetros y el valor de retorno. Esta es una plantilla rápida y acelera su tiempo de documentación. Para protegerse de la ingeniería inversa, debe ofuscar y mantener la interfaz pública. Eclipse adicional muestra un buen mouse pop sobre docu para un método (privado) de que es javadoced

    – AlexWien

    7 febrero 2014 a las 16:20


A menudo escucha la recomendación general de que, en el mejor de los casos, los comentarios simplemente no deberían ser necesario en absoluto. Pero en cuanto 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 usted (especialmente para un principiante) que para cualquier otra persona: cuando le resulta difícil describir qué es una variable o qué hace un método con un solo /** One-line-JavaDoc comment */entonces volverá a pensar automáticamente en lo que ha hecho allí.

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

Sin embargo, en cualquier caso, debe documentar protected métodos: Que alguien que extienda la clase solo llamar este método, o también se le permite anular este método? Si es así, ¿existen condiciones previas y posteriores que debería conocer? ¿Debería llamar super.theMethod() en la versión anulada? (Por cierto: si no se le permite anular el método, entonces debería ser finalpero documentado de todos modos)

Por cierto: yo personalmente comento todopero sepa 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 hace daño, pero ayuda en muchos casos. Tal vez, con respecto private piezas, es solo cuestión de gustos.

Avatar de usuario de Peter Bratton
pedro bratton

No tienes que javadoc nada, pero es muy útil. Más javadocs nunca son una mala cosa.

Según su pregunta, si usa el compilador de documentación de javadoc, los javadocs se compilarán para métodos protegidos, pero no para métodos privados. Sin embargo, no hay razón por la que no se puedan seguir usando como comentarios de código.

¿Ha sido útil esta solución?