Solía pensar que no necesito comentarios si estoy escribiendo código autodocumentado. Sin embargo, me di cuenta de que estaba escribiendo comentarios y los encontré realmente útiles. Para ver cuántos comentarios estoy escribiendo y cuáles son, escribí un script para analizar mis git commits durante los últimos seis años. En total, el siete por ciento de mis líneas aprobadas contenían comentarios. Esta publicación tiene detalles sobre lo que cuenta como comentarios buenos y malos, así como estadísticas adicionales de mi guión.
Javadoc es el más inútil
Una de las razones por las que era escéptico acerca de los comentarios era el predominio de los comentarios al estilo Javadoc. Este estilo de comentarios también existe en otros idiomas. Aquí hay un ejemplo de Python que se me ocurrió, pero que es representativo de este estilo:
El problema con la mayoría de estos comentarios es que transmiten muy poca información. A menudo se trata simplemente de repetir el nombre del método y los nombres de los parámetros en unas pocas palabras. Estos comentarios pueden ser útiles para las API expuestas externamente, pero en una aplicación en la que tiene acceso a todo el código fuente, en su mayoría son inútiles. Si se pregunta qué hace un método o cuál es el rango de entrada válido para un parámetro, es mejor que lea el código para ver qué hace. Este tipo de comentarios ocupan mucho espacio pero no son particularmente valiosos.
Código autodocumentado
En lugar de escribir comentarios de Javadoc, es mejor aprovechar al máximo los nombres de métodos y variables. Cada nombre que use puede ayudar a explicar de qué se trata y cómo se hace. Una buena razón para escribir muchos métodos pequeños en lugar de uno grande es que tiene más lugares para usar nombres descriptivos, que describí aquí .
Cuando comentar
Escribir código autodocumentado le ayudará a largo plazo. Sin embargo, hay ocasiones en las que es útil tener más información. Por ejemplo, un comentario sobre el uso de zonas de marcación en el código siguiente:
Otro ejemplo: a
menudo puede escuchar el consejo “escribir comentarios POR QUÉ, no QUÉ”. Si bien esto probablemente cubre la mayoría de mis comentarios, no es así como pienso en cuándo comentar. En cambio, suelo escribir un comentario cuando hay algo particularmente complicado, ya sea en el dominio o en cómo se está realizando la implementación.
El consejo estándar de la multitud de "no se requieren comentarios" (a la que una vez pertenecí) es reescribir el código para que no sea necesario comentarlo. Sin embargo, esto no siempre es posible. A veces, un dominio es demasiado complicado. A veces, el esfuerzo por reescribir el código sería demasiado grande en comparación con agregar un comentario.
Otra queja sobre los comentarios es que no estarán sincronizados con el código, lo que dificultará su comprensión del código, en lugar de ayudarlo. Aunque sucede a veces, no fue un gran problema para mí. En casi todos los casos que analicé, los comentarios seguían siendo válidos. También fueron muy útiles. Cada vez que me encontraba con uno de estos comentarios, estaba feliz de haberlo escrito. No lleva mucho tiempo olvidar algunos de los detalles y matices del problema que está resolviendo, y tener un comentario con un contexto y una explicación adicionales fue genial.
Registros como comentarios
A veces, recibe un comentario gratuito si registra un mensaje explicativo. En el siguiente ejemplo, la declaración de registro explica lo que sucedió, por lo que no hay necesidad de comentarios.
Análisis de comentarios
Cuando pensé por primera vez en verificar cuántos comentarios hay en todas mis confirmaciones, pensé que una línea sería suficiente para encontrar los comentarios en todas mis confirmaciones de Python (solo comento con #):
git log --author = Henrik -p | grep '^ + [^ +]' | grep '#' | wc -l
Sin embargo, pronto me di cuenta de que necesitaba más detalles. Quería distinguir entre comentarios de final de línea y comentarios de línea completa. También quería saber cuántos "bloques de comentarios" (líneas consecutivas de comentarios) tenía. También decidí excluir los archivos de prueba del análisis. Además, quiero asegurarme de excluir cualquier código comentado que haya terminado allí (desafortunadamente, hubo varios casos de este tipo). Terminé escribiendo un script en Python para hacer el análisis. La entrada al script fue la salida de git log --author = Henrik -p.
En la salida, vi que 1299 de las 17817 líneas que agregué contenían comentarios. Hubo 161 comentarios de final de línea y 464 comentarios de una línea. El bloque de comentarios más largo fue de 11 líneas y hubo 96 casos de bloques de comentarios que tenían 3 o más líneas consecutivas.
conclusiones
Solía pensar que escribir funciones bien nombradas significaría que no se necesitan comentarios. Sin embargo, al observar lo que realmente hice, noté que tiendo a agregar comentarios a partes complejas o poco intuitivas del código. Cada vez que vuelvo a visitar estas partes del programa, me alegro de haber hecho el esfuerzo de agregar un comentario; ¡fueron muy útiles!