Los comentarios en el código

Cuando estuve buscando trabajo en las entrevistas a las que asistí me hicieron preguntas acerca de los comentarios en el código. Yo respondí que últimamente trato de hacer mi código más expresivo, más legible usando nombres apropiados, no escribiendo métodos o funciones muy largas, etc. Y cuando era necesario ponia un comentario para hacer resaltar alguna funcionalidad que no pudiera expresar en el código. Esto al parecer es muy controversial y cada programador tiene sus opiniones.

En el libro de Código Limpio dedica un capítulo acerca del uso correcto de comentarios. Del libro extraigo lo siguiente:

No hay nada más útil que un comentario bien colocado. No hay nada más dañino que un comentario antiguo que propague mentiras y desinformación.

Cuando tenga que escribir un comentario piense si no existe una mejor manera de expresarse en el código. Siempre que escriba un comentario, debe hacer un gesto de desaprobación y sentir su incapacidad para expresarse.

¿Por qué estoy en contra de los comentarios? Porque mienten. Cuanto más antiguo es un comentario y más se aleja del código que describe, mayor es la probabilidad de que sea equivocado. El motivo es sencillo. Los programadores no los pueden mantener.

El código cambia y evoluciona. Los fragmentos cambian de lugar, se bifurcan, se reproducen y se vuelven a combinar. Los comentarios no siempre siguen el ritmo y suelen separarse del código que describen y se convierten en huérfanos sin precisión alguna.
Se podría afirmar que los programadores deben ser lo bastante disciplinados como para mantener los comentarios actualizados, relevantes y precisos. Pero esa energía debería invertirse en crear código claro y expresivo que no necesite comentario alguno.

Los comentarios imprecisos son mucho peor que la ausencia de comentarios. Suelen confundir al usuario. Generan expectativas que nunca se cumplen.

La verdad solo se encuentra en un punto: el código. Solo el código puede contar lo que hace. Es la única fuente de información precisa. Por tanto, aunque los comentarios sean necesarios en ocasiones, dedicaremos nuestra energía a minimizarlos.

Los comentarios no compensan el código incorrecto
Una de las principales motivaciones para crear comentarios es el código incorrecto. Creamos un módulo y sabemos que es confuso y esta desorganizado. Sabemos que es un desastre y entonces decidimos comentar. Error. Mejor límpielo.
El código claro y expresivo sin apenas comentarios es muy superior al código enrevesado y complejo con multitud de comentarios. En lugar de perder tiempo escribiendo comentarios que expliquen el desastre cometido dédiquelo a solucionarlo.

Vienen otras secciones donde explica los tipos de comentarios que sí se deben colocar como: comentarios legales, comentarios informativos, explicar la intención, clarificación, advertir de las consecuencias entre otros.

Vale mucho la pena leer el libro. Yo no estoy en contra de los comentarios sino más bien en hacer uso correcto de ellos para no caer en desinformación que pueden provocar los comentarios sin mantener.

Aun sigo aprendiendo acerca de las buenas practicas de programación así que no me considero experto en el tema.

Espero sea de utilidad. Saludos.

Bibilográfia:

"Código limpio" de Robert C. Martin.

 

Añadir nuevo comentario