Comentarios

Los comentarios del código

Para muchas personas, el poner comentarios en el código de forma profusa era (y para algunas aún sigue siendo) una condición necesaria para considerarlo un código de calidad.

Es cierto que, como desarrolladores, muchas veces nos enfrascamos en solucionar el problema que tenemos entre manos, picando líneas como si no hubiese un mañana y no nos paramos a comentar lo que hacemos. Si acaso dejamos esta tarea para el final. Pero, ¿es realmente necesario e incluso deseable comentar todo el código que escribimos?.

El código de calidad debe ser facilmente legible. Un código bueno es aquel que se entiende facilmente y los comentarios deben facilitar esta comprensión.

Pero sólo si son necesarios. El mejor código es autoexplicativo y no necesita de comentarios. En cierto modo, la necesidad de comentar un fragmento de código es un fracaso. Una muestra de nuestra incapacidad para escribir código legible.

Si usamos nombres apropiados en nuestras variables y funciones, evitamos anidamientos multinivel, mantenemos nuestras funciones con pocos argumentos, tratamos de que nuestro código sea lo más sencillo y comprensible posible… en definitiva, si escribimos buen código, los comentarios son innecesarios la mayor parte del tiempo y sólo deberíamos usarlos para aclaraciones de tipo técnico que no puedan entenderse facilmente por sí mismas.

Hay algunas situaciones concretas en que este mal uso de los comentarios se hace más patente. Por ejemplo, si contienen información inapropiada. Los comentarios son para lo que son: para aclaraciones técnicas sobre el código y no para poner datos como el autor, la fecha, etc. Para eso hay otras herramientas como el control de versiones, los archivos de licencia, etc.

Además, los comentarios se pueden quedar facilmente obsoletos en proyectos en desarrollo. Es nuestra responsabilidad evitar ésto. Los comentarios deben siempre actualizarse y evolucionar junto al código. Mucho cuidado con comentarios obsoletos.

Otro aspecto a evitar son los comentarios con información redundante. Por ejemplo, el javadoc que simplemente documenta el tipado de los parámetros de la función sería un comentario redundante. no proporciona ninguna información que no se pueda saber simplemente viendo la cabecera de la función. Mal.

Y, por favor, si ponemos un comentario, hay que cuidar minimamente su redacción. Pocas cosas duelen mas a los ojos que comentarios con errores ortográficos o sintácticamente mal construídos. Los comentarios son parte del código y su mala redacción afecta negativamente a la calida del mismo.

Aunque, la mayor abominación quizá sea la de los fragmentos de código comentado. Si un código no se usa, se borra. Punto. Desde que existe el control de versiones no tiene sentido tener miedo a borrar cosas. Por favor, si encuentras un fragmento de código comentado borralo inmediatamente.

Pues esto es de lo que venía a hablar hoy. ¿Algún comentario?

Comparte

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *