Mejores prácticas en redacción de comentarios y documentación

Comentar hoy en día es más fácil que nunca. En Java, hay algunas buenas técnicas para vincular comentarios a clases, y los IDE de Java son buenos para hacer shells de comentarios para usted. Los lenguajes como Clojure incluso le permiten agregar una descripción de una función en el código de la función como argumento.

Sin embargo, todavía vivimos en una época en la que a menudo hay comentarios obsoletos o deficientes escritos por buenos desarrolladores. Estoy interesado en mejorar la solidez y la utilidad de mis comentarios.

En particular, estoy interesado en Java / Clojure / Python aquí, pero las respuestas no necesitan ser específicas del idioma.

¿Hay alguna técnica emergente que valide los comentarios y detecte automáticamente comentarios "débiles" (por ejemplo, comentarios con números mágicos, oraciones incompletas, etc.) o comentarios incorrectos (por ejemplo, detectar variables mal escritas o similares).

Y lo que es más importante: ¿existen "políticas o estrategias de comentarios" aceptadas? Hay muchos consejos sobre cómo codificar, pero ¿qué pasa con "cómo comentar?"

• Los nombres / documentación deben decirle lo que está haciendo.

• La implementación debería decirle cómo lo está haciendo.

• Los comentarios deben decirte por qué lo haces de la manera que lo haces.

Esto podría ser controvertido, pero mi consejo sería escribir POCOS comentarios como sea posible. Utilice nombres de clase claros y agradables, nombres de variables y nombres de métodos en su lugar. Escriba su código de la manera más clara posible; y considere que este es el atributo más importante de su código (aparte de que cumple con sus requisitos). Solo escribe un comentario si has hecho un método lo más claro posible y aún piensas que requiere una explicación más detallada.

Y tenga una práctica organizativa, que cada vez que alguien cambie una clase de alguna manera, debe asegurarse de que los comentarios sigan siendo correctos.

No estoy seguro acerca de otros idiomas, pero Python le permite escribir doctest que son una forma de comentarios de autovalidación. Por supuesto, no deben usarse en lugar de pruebas de unidades reales, sino que son un método rápido y fácil de documentar funciones específicas que pueden no ser tan obvias como deberían ser. Vienen con el beneficio adicional de poder ejecutar las pruebas de comentarios para verificar que los comentarios siguen siendo correctos (al menos la parte de ellos que contiene pruebas).

Una de las ubicaciones más autorizadas para encontrar cómo usar el comentario de código para generar documentación automáticamente es seguramente doxygen . Aunque podría haber más de esas herramientas.

Esto define el estándar de redacción de comentarios que se debe seguir para generar documentación automáticamente. Sin embargo, esto da más estructura pero no se valida semánticamente; ¡Por ejemplo, no puede comprobar si ha utilizado un inglés engañoso para describir el propósito de una función!

Si bien, esto es lo mejor que estructuran los comentarios, personalmente creo que se necesita más documentación para que el código sea más fácil de mantener como tal. Algún tiempo atrás hubo una pregunta en P.SE ¿Puede el código ser la documentación en herramientas de desarrollador de código abierto? ¿Con qué frecuencia es? Por supuesto, esto también se aplica a proyectos de código abierto.

Para hacer que el código sea más fácil de mantener: es prácticamente más importante que exista una documentación externa que ayude a crear una estructura de cómo tratar el código, y luego los comentarios dentro del código deben restringirse para ver

Creo que si desea definir las políticas para la redacción de comentarios , debe incluir como un enfoque holístico incluido en el estándar de codificación. Vea esto: ¿Cuáles podrían ser algunos inconvenientes al introducir una guía de estilo y software de generación de documentación en un equipo de desarrollo?

Por lo general, los comentarios constituyen menos del 5% del código. Y en la práctica, mientras que las revisiones de código en sí atraen mucho menos atención (sobre otros aspectos del desarrollo), es prácticamente difícil que también se revisen los comentarios.

¿Hay alguna técnica emergente que valide los comentarios y detecte automáticamente comentarios "débiles" (por ejemplo, comentarios con números mágicos, oraciones incompletas, etc.) o comentarios incorrectos (por ejemplo, detectar variables mal escritas o similares).

Existe una técnica bien conocida: se llama "revisión de código" y tiene una hermana llamada "programación de pares". No esperes nada "automágicamente" aquí.

Y lo que es más importante: ¿existen "políticas o estrategias de comentarios" aceptadas? Hay muchos consejos sobre cómo codificar, pero ¿qué pasa con "cómo comentar?"

"Código completo" contiene no solo todo sobre cómo codificar, sino también capítulos sobre "cómo comentar", especialmente sobre cómo escribir código autodocumentado.

Una fuente específica de Java que he disfrutado es la sección Cómo escribir comentarios de documentos de Oracle para la herramienta Javadoc :

Este documento describe la guía de estilo, las convenciones de etiquetas e imágenes que utilizamos en los comentarios de documentación para programas Java escritos en Java Software, Sun Microsystems.

Y artículo 44: escriba comentarios de documentos para todos los elementos de API expuestos :

Si una API debe ser utilizable, debe documentarse. Tradicionalmente, la documentación de la API se generaba manualmente, y mantenerla sincronizada con el código era una tarea difícil. El entorno de programación Java facilita esta tarea con la utilidad Javadoc. Javadoc genera documentación API automáticamente desde el código fuente con comentarios de documentación especialmente formateados, más comúnmente conocidos como comentarios de documentos.

de Effective Java 2nd Edition .