¿Código autodocumentado vs Javadocs?

18

Recientemente he estado trabajando en la refactorización de partes de la base de código con la que estoy trabajando actualmente, no solo para comprenderlo mejor, sino también para que sea más fácil para otros que están trabajando en el código.

Tiendo a inclinarme al lado de pensar que el código autodocumentado es bueno . Simplemente creo que es más limpio y si el código habla por sí mismo, bueno ... Eso es genial .

Por otro lado tenemos documentación como javadocs. También me gusta esto, pero existe un cierto riesgo de que los comentarios aquí se desactualicen (así como los comentarios en general, por supuesto). Sin embargo, si están actualizados, pueden ser extremadamente útiles, por ejemplo, para comprender un algoritmo complejo.

¿Cuáles son las mejores prácticas para esto? ¿Dónde trazas la línea entre el código autodocumentado y los javadocs?

Andreas Johansson
fuente

Respuestas:

24

El código autodocumentado (y los comentarios en código) y los comentarios Javadoc tienen dos audiencias objetivo muy diferentes.

El código y los comentarios que permanecen en el archivo de código son para desarrolladores. Desea abordar sus inquietudes aquí: facilitar la comprensión de lo que hace el código y por qué el código es como es. El uso de nombres de variables apropiados, métodos, clases, etc. (código autodocumentado) junto con comentarios logra esto.

Los comentarios Javadoc son típicamente para usuarios de la API. Estos también son desarrolladores, pero no les importa la estructura interna del sistema, solo las clases, métodos, entradas y salidas del sistema. El código está contenido dentro de un cuadro negro. Estos comentarios deben usarse para explicar cómo hacer ciertas tareas, cuáles son los resultados esperados de las operaciones, cuándo se lanzan excepciones y qué significan los valores de entrada. Dado un conjunto de documentación generado por Javadoc, debería ser capaz de comprender completamente cómo usar sus interfaces sin tener que mirar una línea de su código.

Thomas Owens
fuente
+1, esa es una buena decisión. Creo que mi principal agarre con esto es que no lo veo como dos audiencias objetivo diferentes, pero tienes razón.
Andreas Johansson el
1
@Andiaz: me parece útil diferenciar entre los bordes externos del sistema (como una API de servicio) y las clases dentro de él. A menudo trabajo en proyectos donde la convención es javadoc todos los métodos públicos, pero me preocupo mucho más en las clases externas para dar alguna indicación de cómo se debe usar la clase (y el sistema). En las clases internas, supongo que el lector tiene más conocimiento del dominio y minimiza el javadoc, permitiendo que los nombres de los métodos hablen más por sí mismos.
Steve Jackson
3
@SteveJackson Estoy de acuerdo, sin embargo, me encontré usando más Javadocs (incluso en miembros privados) ya que los IDEs (al menos Eclipse y NetBeans) muestran los comentarios de Javadoc en la información sobre herramientas de finalización de código. Por supuesto, no son tan limpios como las interfaces públicas, proporcionan consejos / notas a otros desarrolladores.
Thomas Owens
24

El código dice cómo . Los comentarios dicen por qué , y tal vez incluso por qué no .

Es su trabajo proporcionar a los futuros lectores y mantenedores de su código. Pon todo lo que puedas en el código y el resto en los comentarios.

Tenga en cuenta que las cosas más difíciles de capturar son las decisiones de diseño, recuérdelas también.


fuente
2
+1: No es "uno u otro" en un sentido exclusivo. Es a la vez en un sentido inclusivo.
S.Lott
Definitivamente estoy de acuerdo con esto. ¿Hay algo más que considerarías cuando se trata de javadocs en particular? Como, puedo imaginar que describir lo que hace un método podría ser útil, por ejemplo, para API.
Andreas Johansson el
Se puede acceder fácilmente a Javadocs desde la mayoría de los IDE. Facilite la navegación para obtener más información.
+1: Los mejores comentarios que he visto incluyen referencias a los documentos donde se analizaron en profundidad los algoritmos utilizados; eso no es algo que pueda documentarse por sí mismo en nombres de variables / métodos, y no necesariamente pertenece a los comentarios de documentos, ya que el algoritmo es parte de la implementación y no de la interfaz .
Donal Fellows
4

El uso de Javadocs no hace una diferencia real, ya que los documentos generados contienen el nombre de sus funciones junto con el texto de los comentarios, no hay absolutamente ninguna razón por la que deba repetir algo en los comentarios que esté claro en el nombre de la función.

Si, por otro lado, tiene una función en la que primero hay que mirar la implementación para comprender para qué sirve (por lo tanto, no hacer que esta información esté disponible para Javadocs), entonces el código es en mi humilde opinión, no se documenta automáticamente, no importa qué tan clara es la implementación.

Doc Brown
fuente
3
+1 mi favorito es cuando el estándar del código de la empresa requiere métodos documentados, pero todos usan un generador que simplemente repite lo que el código ya dice. Tedioso e inútil.
Kryptic
1

Creo que con javadocs, las cosas son las mismas que con cualquier documentación, la regla principal es:

sigue a la audiencia

No muchas personas leen sus javadocs? En caso afirmativo, tiene sentido invertir esfuerzos para hacerlo bien.

¿ Sus lectores tienden a omitir la lectura de códigos a favor de estudiar javadocs? En caso afirmativo, tiene el doble de sentido gastar esfuerzos en escribirlo bien.

  • Este es exactamente el caso con la documentación JDK . Guess Sun / Oracle hizo un gran esfuerzo en estos y parecen tener una buena recompensa en los documentos de API que la comunidad usa mucho.

Ahora, ¿es tu caso? Si no, piense dos veces si los esfuerzos invertidos en javadocs están justificados.

Como ya se señaló anteriormente, escuche a la audiencia para descubrir el camino.

  • Si escucha quejas activas sobre documentación insuficiente, considere invertir en mejorarla.
     
    Si, por otro lado, todo lo que escuchas es que los desarrolladores se quejan de las reglas de braindead que los obligan a perder el tiempo en escribir inútilmente, entonces es muy probable que tus esfuerzos de javadocs sean como invertir en hipotecas de alto riesgo . Piense en mejores inversiones en su lugar.
mosquito
fuente
0

Solo quiero comentar sobre la preocupación de que los comentarios Javadoc puedan quedar desactualizados. Si bien @JonathanMerlet tiene razón al decir que el Javadoc debe ser estable, también puede ayudar al revisar el Javadoc y los comentarios, así como el código durante la revisión por pares. ¿Los comentarios coinciden con lo que está haciendo el código? Si no, que es incorrecto, e insista en que el desarrollador lo arregle. Intenta alentar a otros desarrolladores a hacer lo mismo. Esto ayuda a mantener actualizada no solo la documentación externa (comentarios Javadoc), sino también cualquier comentario de código regular. Esto ayuda a los desarrolladores que vienen después de su refactorización a comprender el código más rápida y fácilmente, y hace que el mantenimiento sea mucho más simple en el futuro.

Eric Hydrick
fuente
-1

Creo que javadocs es apropiado para las partes que deben mantenerse estables (API) de modo que se minimice el riesgo de que los comentarios se desactualicen, mientras que el código de autodocumentación es excelente para lo que está sujeto a cambios frecuentes (implementación). Por supuesto, las API pueden cambiar durante el curso del proyecto, pero tener el encabezado justo antes de la declaración, mantener ambas sincronizadas no es tan difícil (en comparación con los comentarios en varias líneas que explican varias líneas de código)

Jonathan Merlet
fuente