La norma general en lo que refiere a código limpio es evitar los comentarios en la medida de los posible. En el mejor de los casos, los comentarios no son más que un mal necesario. Su principal objetivo será compensar nuestra incapacidad de expresarnos correctamente a través del código.
Si el código es lo suficientemente bueno, se explica a sí mismo. Por lo tanto, escribir el mejor código posible debe ser nuestra prioridad, no intentar solucionarlo mediante explicaciones en comentarios. Muchos, de hecho, pueden obviarse si elegimos buenos nombres para las variables y las funciones, como vimos en el capítulo 2.
No obstante, hay determinadas situaciones en las que un comentario puede tener sentido. Algunas de estas situaciones son las siguientes:
- Cuando se nos exija por razones legales añadir un comentario específico encabezando ficheros.
- Para informar sobre algo muy concreto, por ejemplo, qué hace un determinado patrón Regex que estamos utilizando.
- Como explicación de intenciones sobre algo para lo que no hemos encontrado solución mejor y que creemos que no queda claro solo por el código.
- De modo similar al punto anterior, para clarificar qué estamos haciendo cuando utilizamos una librería externa cuyos nombres no aclaren del todo el uso que estamos haciendo de sus métodos.
- Cuando queremos advertir de las (malas) consecuencias que pueden acontecer si se decide ejecutar determinada parte del código.
- TODOs cuando algo no se puede hacer en ese momento. Como apunte particular, recomiendo añadir al comentario un ticket en la plataforma de gestión de proyectos que estés utilizando para completar la información.
Debemos evitar en la medida de los posible el resto de comentarios. Los que redundan en lo que ya explica el código, haciéndolos innecesarios. Esto incluye los que listan los parámetros de una función, que ya de por sí deberían tener nombres autoexplicativos. No queremos añadir ruido.
Tampoco queremos comentarios que puedan dar lugar a malentendidos. Si escribimos un comentario, tenemos que hacer nuestro un esfuerzo porque sea el mejor comentario posible.
No debemos guardar en comentarios quién escribió cada parte de código, para eso ya tenemos controladores de versiones (¡hola, Git!). Que, por cierto, también eliminan la necesidad de dejar código comentado. Si en un futuro necesitas código del pasado, siempre puedes recuperarlo.
Para finalizar, si decides escribir un comentario, que no contenga demasiada información y esté en el lugar que corresponda.