usar - ¿Usas Javadoc para cada método que escribes?

javadoc tags (19)

@Claudiu

Cuando escribo código que otros usarán - Sí. Cada método que alguien más puede usar (cualquier método público) debe tener un javadoc al menos indicando su propósito obvio.

@Daniel Spiewak

Documentaré a fondo todos los métodos públicos en cada clase de API. Las clases que tienen miembros públicos pero que no están destinadas al consumo externo están marcadas de forma destacada en la clase javadoc. También documenté cada método protegido en cada clase API, aunque en menor medida. Esto va en la idea de que cualquier desarrollador que extienda una clase API ya tendrá un concepto justo de lo que está sucediendo.
Finalmente, ocasionalmente documentaré métodos privados y paquetes privados para mi propio beneficio. Cualquier método o campo que creo que necesita alguna explicación en su uso recibirá documentación, independientemente de su visibilidad.

@Paul de Vrieze

Para cosas, como getters y setters triviales, comparta el comentario entre entonces y describa el propósito de la propiedad, no del getter / setter

/** * Get the current value of the foo property. * The foo property controls the initial guess used by the bla algorithm in * {@link #bla} * @return The initial guess used by {@link #bla} */ int getFoo() { return foo; }

Y sí, esto es más trabajo.

@VonC

Cuando se rompe un método complejo enorme (debido a una razón de complejidad ciclomática alta ) en:

un método público llamando
varios métodos privados que representan los pasos internos del público

, también es muy útil para javadoc los métodos privados, aunque esa documentación no estará visible en los archivos de la API javadoc.
Aún así, le permite recordar más fácilmente la naturaleza precisa de los diferentes pasos de su complejo algoritmo.

Y recuerde: los valores límite o las condiciones de contorno también deben ser parte de su javadoc.

Además, javadoc es mucho mejor que simple "// comment" :

IDE lo reconoce y lo utiliza para mostrar una ventana emergente cuando mueve el cursor sobre una de sus funciones, javadoc-ed. Por ejemplo, una constante , es decir, una variable final estática privada, debe tener un javadoc, especialmente cuando su valor no es trivial. Caso en punto: regexp (su javadoc debe incluir la expresión regular en su forma no escapada, cuál es el propósito y un ejemplo literal que coincida con la regexp)
Puede ser analizado por herramientas externas (como xdoclet )

@Domci

Para mí, si alguien lo va a ver o no, no importa; no es probable que sepa qué código oculto escribí después de un par de meses. [...]
En resumen, comente la lógica, no la sintaxis, y hágalo solo una vez, en un lugar apropiado.

@Miguel Ping

Para comentar algo, debes entenderlo primero. Cuando intentas comentar una función, en realidad estás pensando en lo que hace el método / función / clase, y esto te hace ser más específico y claro en tu javadoc, lo que a su vez te hace escribir un código más claro y conciso, que es bueno. .

¿Debo escribir Comentarios de Doc para todos mis métodos de Java?

Asumido en todas las respuestas hasta ahora es que los comentarios serán buenos comentarios. Como todos sabemos, ese no es siempre el caso, a veces incluso son incorrectos. Si tiene que leer el código para determinar su intención, los límites y el comportamiento de error esperado, entonces el comentario es deficiente. Por ejemplo, el hilo del método es seguro, puede ser cualquier arg nulo, puede devolver nulo, etc. Los comentarios deben ser parte de cualquier revisión de código.

Esto puede ser aún más importante para los métodos privados, ya que un mantenedor de la base de código tendrá que lidiar con problemas que un usuario de la API no tendrá.

Quizás los IDE deberían tener una característica que permita el uso de un formulario de documentación para que el desarrollador pueda marcar varias propiedades que son importantes y aplicables para el método actual.

Cuando escribo el código para mí - NO . En este caso, la documentación de Java es una pérdida de tiempo.

Cuando escribo código que otros usarán - Sí . Cada método que alguien más puede usar (cualquier método público) debe tener un documento de Java que indique al menos su propósito obvio. Para una buena prueba, ejecute la utilidad de creación javadoc en su código (ahora se me olvida la línea de comando exacta). Navegue a través de la página web que genera. Si está satisfecho con una biblioteca con ese nivel de documentación, está satisfecho. Si no, escriba más javadocs en su código .

Documentaré a fondo todos los métodos públicos en cada clase de API. Las clases que tienen miembros públicos pero que no están destinadas al consumo externo están marcadas de forma destacada en la clase javadoc. También documenté cada método protegido en cada clase API, aunque en menor medida. Esto va en la idea de que cualquier desarrollador que extienda una clase API ya tendrá un concepto justo de lo que está sucediendo.

Finalmente, ocasionalmente documentaré métodos privados y paquetes privados para mi propio beneficio. Cualquier método o campo que creo que necesita alguna explicación en su uso recibirá documentación, independientemente de su visibilidad.

Hay otra razón por la que deberías usar javadocs. Para comentar algo, debes entenderlo primero. Cuando intentas comentar una función, en realidad estás pensando en lo que hace el método / función / clase, y esto te hace ser más específico y claro en tu javadoc, lo que a su vez te hace escribir un código más claro y conciso, que es bueno. .

Intento al menos documentar cada propiedad y método público e interfaz, para que las personas que llaman a mi código sepan qué son las cosas. También trato de comentar la mayor cantidad posible en línea también por cuestiones de mantenimiento. Incluso los proyectos ''personales'' que hago en mi propio tiempo solo para mí, intento javadoc solo porque puedo guardarlo durante un año y volver a él más tarde.

Javadoc puede ser realmente útil para bibliotecas y componentes reutilizables. Pero seamos más prácticos. Es más importante tener código de autoexplicación que javadoc. Si imaginas un gran proyecto de legado con Javadocs, ¿confiarías en eso? No lo creo ... Alguien ha agregado Javadoc, luego la implementación ha cambiado, se agregó una nueva característica (eliminada), por lo que el Javadoc quedó obsoleto. Como mencioné, me gusta tener javadocs para bibliotecas, pero para proyectos activos preferiría

pequeñas funciones / clases con nombres que describen lo que hacen
casos claros de prueba unitaria que dan una explicación de lo que hacen las funciones / clases

Me gusta escribir comentarios de javadoc siempre que no sea trivial, escribir comentarios de javadoc cuando se usa un IDE como eclipse o netbeans no es tan problemático. Además, cuando escribes un comentario de javadoc, te obligan a pensar no solo en lo que hace el método, sino también en qué hace exactamente el método y las suposiciones que has hecho.

Otra razón es que una vez que haya entendido su código y lo haya refabricado, javadoc le permite olvidarse de lo que hace, ya que siempre puede consultarlo. No estoy abogando por olvidar intencionalmente lo que hacen sus métodos, pero es solo que prefiero recordar otras cosas que son más importantes.

No se debe confiar en el documento de Java, ya que impone una carga a los desarrolladores que realizan cambios para mantener el documento de Java y el código.

Los nombres de las clases y los nombres de las funciones deberían ser lo suficientemente explícitos como para explicar lo que está sucediendo.

Si explicar qué hace una clase o método hace que su nombre sea demasiado largo para tratar, la clase o el método no se enfoca lo suficiente, y se debe refactorizar en unidades más pequeñas.

No, no comento todos los métodos, variables, clases, etc.

Aquí hay una cita de "Clean Code: A Handbook of Agile Software Craftsmanship":

Es simplemente una tontería tener una regla que diga que cada función debe tener un javadoc, o cada variable debe tener un comentario. Comentarios como este solo desordenan el código, revelan mentiras y dan lugar a confusión general y desorganización.

Debe existir un comentario si, y solo si, agrega información importante para el usuario previsto del método, la variable, la clase, etc. Lo que constituye "importante" merece consideración y podría ser un recordatorio para mí mismo / si vuelvo a este método / clase / etc., una consecuencia / efecto secundario del método, motivación de por qué la cosa existe (en el caso de que algún código supere una deficiencia / error de alguna biblioteca o sistema), información importante sobre el rendimiento o cuando es apropiado llamar, etc.

Lo que no es un buen comentario, pero indica que el código en sí mismo debe ser reescrito / modificado es un comentario que explica los detalles de un método o función compleja y oscura. En cambio, prefiera un código más corto y claro.

Para cosas, como getters y setters triviales, comparta el comentario entre entonces y describa el propósito de la propiedad, no del getter / setter.

/** * Get foo * @return The value of the foo property */ int getFoo() { return foo; }

No es útil Mejor haz algo como:

Y sí, esto es más trabajo.

Para mí, si alguien lo va a ver o no, no importa; no es probable que sepa qué código oculto escribí después de un par de meses. Hay algunas pautas:

Las API, las clases de marco y los métodos estáticos reutilizables internos deben comentarse exhaustivamente.
La lógica en cada pieza complicada de código debe explicarse en dos lugares: lógica general en javadoc y lógica para cada parte significativa del código en su propio comentario.
Las propiedades del modelo deben comentarse si no son obvias. Por ejemplo, no tiene sentido comentar el nombre de usuario y la contraseña, pero el tipo debe tener al menos un comentario que diga cuáles son los valores posibles para el tipo.
No documenta getters, setters ni nada hecho "por el libro". Si el equipo tiene una forma estándar de crear formularios, adaptadores, controladores, fachadas ... No los documenta, ya que no tiene sentido si todos los adaptadores son iguales y tienen un conjunto de métodos estándar. Cualquiera que esté familiarizado con Framework sabrá para qué sirven, suponiendo que la filosofía de la estructura y la forma de trabajar con ella estén documentadas en alguna parte. En estos casos, los comentarios significan desorden adicional y no tienen ningún propósito. Hay excepciones a esto cuando la clase hace algo no estándar, entonces el comentario breve es útil. Además, incluso si estoy creando formularios de forma estándar, me gusta dividir partes del formulario con comentarios breves que dividen el código en varias partes, por ejemplo, "la dirección de facturación comienza aquí".

En resumen, comente la lógica, no la sintaxis, y hágalo solo una vez, en un lugar apropiado.

Probablemente deberías documentar todos tus métodos realmente. Los más importantes son los métodos API públicos (especialmente los métodos API publicados). Los métodos privados a veces no están documentados, aunque creo que deberían serlo, solo por claridad, lo mismo ocurre con los métodos protegidos. Sus comentarios deben ser informativos y no solo reiterar lo que hace el código.

Si un método es particularmente complejo, se recomienda que lo documente. Algunas personas creen que el código debe escribirse claramente para que no requiera comentarios. Sin embargo, esto no siempre es posible, por lo que los comentarios deben usarse en estos casos.

Puede automatizar la generación de comentarios de Javadoc para getters / setters desde Eclipse a través de las plantillas de código para ahorrar en la cantidad de documentación que tiene que escribir. Otro consejo es usar @ {$ inheritDoc} para evitar la duplicación de comentarios de código entre interfaces y clases de implementación.

Puede ejecutar javadoc contra código que no tenga comentarios javadoc y generará javadocs bastante utilizables si proporciona nombres detallados a sus métodos y parámetros.

Si el método es, evidentemente evidente, podría omitir un comentario de javadoc.

Comentarios como

/** Does Foo */ void doFoo();

Realmente no son tan útiles. (Ejemplo excesivamente simplista, pero entiendes la idea)

Siento que al menos debería haber comentarios con respecto a los parámetros aceptados y los tipos de devolución en términos de lo que son.
Uno puede omitir los detalles de implementación en caso de que los nombres de las funciones lo describan por completo, por ejemplo, sendEmail (..) ;

Todas las bases cubiertas por otros ya; una nota adicional:

Si te encuentras haciendo esto:

/** * This method currently launches the blaardh into the bleeyrg. */ void execute() { ... }

Considera cambiarlo a esto:

void launchBlaardhIntoBleeyrg() { ... }

Esto puede parecer un poco obvio, pero en muchos casos la oportunidad es fácil de perder en su propio código.

Finalmente, tenga en cuenta que el cambio no siempre se desea; por ejemplo, se puede esperar que el comportamiento del método evolucione con el tiempo (tenga en cuenta la palabra "actualmente" en JavaDoc).

en pocas palabras: SÍ

El tiempo que necesita para pensar si debe escribir un documento es invertirlo mejor en la redacción de un documento.

Escribir un texto único es mejor que gastar tiempo para no documentar el método al final.

en una compañía anterior, solíamos usar el formateador de código jalopy con eclipse. Eso agregaría javadoc a todos los métodos, incluido el privado.

Hizo la vida difícil documentar setters y getters. Pero qué diablos. Tienes que hacerlo, lo haces. Eso me hizo aprender algunas funciones macro con XEmacs :-) Puedes automatizarlo aún más escribiendo un analizador de Java y un comentarista como ANTLR creó hace varios años :-)

Actualmente, documenté todos los métodos públicos y cualquier cosa de más de 10 líneas.