¿Código autodocumentado vs Javadocs?

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?

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.

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.

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.

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.

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.

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)