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

20

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?"

jayunit100
fuente

Respuestas:

40
  • 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.

monstruo de trinquete
fuente
66
Los comentarios también deben decir por qué usted está no haciendo de otra manera - es decir, las opciones de diseño importantes - porque los futuros mantenedores no van a tener esta información de otra manera.
2
Creo que hay muchas veces que un comentario debería decir QUÉ estás haciendo también. Esta idea de solo comentarios de "por qué" es un antipatrón en mi opinión. Es un mito que puedes escribir todo el código lo suficientemente claro como para que cualquier programador pueda entenderlo de un vistazo, y mi experiencia es que la mayoría de los programadores que piensan que escriben código limpio no lo hacen. Es lo mismo que decir: "No tengo que nombrar esta función descriptivamente porque cualquiera puede leer el código en la función para ver qué hace". - eso tampoco tiene sentido, ¿verdad?
dallin
2
@dallin si su código no es claro sobre lo que está haciendo; considere refactorizarlo. de lo contrario, agregue un comentario que explique por qué se implementa de esa manera (que también explica cómo hacerlo mejor) Su comparación con nombres descriptivos es manzanas / naranjas, un nombre descriptivo deja en claro dónde se utiliza la función y es posible que no tenga acceso al código fuente de la función.
Ratchet Freak
@dallin: "Es un mito que puedes escribir todo el código lo suficientemente claro como para que cualquier programador pueda entenderlo de un vistazo", el tío Bob querría hablar contigo. - "No tengo que nombrar esta función descriptivamente porque cualquiera puede simplemente leer el código en la función para ver qué hace", dar nombres buenos y claros a las variables y métodos es exactamente cómo los programadores deben aclarar cuál es su código ¡está haciendo!
klaar
14

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.

Dawood dice que reinstalar a Monica
fuente
1
Este es un buen comienzo, pero creo que para satisfacer la pregunta del OP deberá escribir algo que aborde sus preocupaciones reales con respecto a la validación automática.
Robert Harvey
2
+1: también creo que los comentarios solo deben usarse para explicar por qué se ha escrito el código. Sé lo que if (a == b) then c();hace, pero si no sé por qué lo hace, es cuando se debe usar un comentario :)
Deco
Deco: estoy completamente de acuerdo. Los comentarios son buenos cuando quiero entender cómo un método en particular encaja en el proceso como un todo. En otras palabras, POR QUÉ llamaría a este método, o POR QUÉ hace lo que hace.
Dawood dice reinstalar a Mónica el
Además de aclarar el código escrito, también debemos asegurarnos de retener ideas (pensamientos), pensamientos, etc., usando TODO comentarios. Por ejemplo, si ve que una función / clase es capaz de manejar el tamaño de datos actual correctamente, pero potencialmente no podrá manejar la carga después de 2 años, asegúrese de escribir su observación allí usando el comentario TODO. Los futuros desarrolladores apreciarán sus esfuerzos. Nunca intentes anotar estas cosas en un documento txt / word separado, mientras escribes código, nadie realmente hace referencia a dichos documentos.
TechCoze
5

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).

Josh Smeaton
fuente
1
Y Sphinx compara el código con la documentación para proporcionar métricas de cobertura.
S.Lott
3

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.

Dipan Mehta
fuente
1
No estoy de acuerdo con la última oración aquí. Acabo de terminar un contrato, trabajando con un líder de equipo que dio revisiones muy detalladas. Sus revisiones siempre incluían los comentarios: cómo estaban redactadas, si los nombres de las variables eran correctos, si contenían toda la información que un futuro desarrollador podría desear saber. En poco tiempo, supe lo que esperaba ver en cada comentario, y pude producir comentarios a su nivel. Por lo tanto, siempre que sea política de la organización tener revisiones de código e incluir comentarios en la revisión de código, entonces sucederá.
Dawood dice reinstalar a Mónica el
Este suele ser el único tipo de comentario que escribo, especialmente para los métodos para documentar lo que entra y lo que sale de él (trabajo con lenguajes mecanografiados libremente).
DanMan
2

¿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.

Doc Brown
fuente
+1 para el código completo. Clean Code de Robert Martin también tiene un buen capítulo sobre cómo escribir recomendaciones útiles. No estoy seguro sobre el mundo Java, pero en el mundo .NET tenemos ReSharper, que puede 'automágicamente' referencias Validar para elementos de código en los comentarios :)
MattDavey
0

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 .

EGHM
fuente