¿Comentar código y mejorar la calidad del software?

Eduardo el 5 de Marzo de 2008 , en: General

En esta entrega, vamos a profundizar en el fino arte de comentar código.

En principio… ¿por qué deberíamos comentar nuestros códigos?

Quiero empezar citando a Ryan Campbell:

“comentar el código es como limpiar el cuarto de baño; nadie quiere hacerlo, pero el resultado es siempre una experiencia más agradable para uno mismo y sus invitados”

Poner comentarios en el medio de código sin gramática, va mucho mas allá de escribir /* */ por cada línea explicando el funcionamiento de procesos tan obvios como estúpidos. Se requiere casi un “don” para poder explicar en pocas palabras el funcionamiento de algoritmos complejos a otras personas que no seamos nosotros mismos.

¿Que objetivo tiene este artículo?… vamos a intentar comunicarnos con nuestro “yo del futuro”. ¿Estoy loco? no no, hablo de que hagamos código que podamos leer cuando lo agarremos en el futuro (1 año después por ejemplo).

Mi biblioteca de archivos viejos, contiene códigos fuente ilegibles e inentendibles para mi “yo del presente”. Y eso es porque en el pasado, tenia “otra mente” (no, no es que fui abducido por extraterrestres) en el sentido de que mi mente ha evolucionado y ya no recuerdo mi modo de pensar en ese tiempo, por lo tanto, las soluciones y algoritmos que me parecian obvios ya no lo son tanto ahora.

En este artículo voy a tratar de responder estas preguntas: ¿Cómo comentar? ¿Que comentar? y ¿Los comentarios mejoran la calidad del software?

¿Cómo comentar?

Los comentarios erróneos o difíciles de entender pueden confundir a los lectores, incluso si el código escrito es obvio. Este tipo de comentarios es peor que código sin comentar. Los comentarios que repiten las obviedades de las sentencias de código no añaden valor al código y por el contrario, distraen la atención.

La mejor manera de comentar es hacerlo “eficientemente”, y para ello a mi parecer, los comentarios deben ser:

Fáciles de modificar:

No hagas de tus comentarios obras de arte en ascii, ni te creas que estás dibujando en paint con letras. Si tu comentario está rodeado por un marco de # sencillamente nadie va a actualizarlo debido al esfuerzo que supone volver a encerrar todo en #.
Descriptivos:

Pero no obvios. Si la función se llama “SumarNumeros” no escribas un comentario del tipo “Función para sumar números”. El exceso de este tipo de comentarios insulta la inteligencia del lector.
Párrafos, antes que líneas largas:

Es mejor ocupar 2 líneas de comentario, antes que escribir una gran línea que se sale por fuera de nuestra pantalla.
Enfocados en el “por qué” en lugar del “cómo”:

Un mal comentario:
/* Si la bandera de la cuenta es cero… */
if (banderaDeCuenta == 0) . . .

Un buen comentario:
/* Si se establece una nueva cuenta… */
if (banderaDeCuenta == 0) . . .
Cortos, no abreviados:

Los comentarios deben ser fáciles de leer para explicar el código. No escribas comentarios que sean mas difíciles que el código que intentas explicar.

¿Que comentar?

Un buen código debería ser “autoexplicativo”, aunque no siempre logramos esto.
Por ello, es necesario documentar las partes que no sean entendibles a simple vista, que tengan “chapuzas” o “hacks”, funciones muy largas, y todo tipo de “mala programación” que requiera una concentración no-normal para entender lo que hace el código.

La recomendación de oro:

Deja que el código hable por si mismo, de esta forma podrás minimizar los comentarios a escribir.

… pero, entonces ¿comentar el código mejora la calidad?

Directamente NO. Comentar el código mejora el mantenimiento del mismo, facilita su lectura y entendimiento, y es mucho más importante cuando se trabaja con un grupo de personas.

Comentar no influye directamente en la calidad del software, pero aumenta nuestra calidad en programación. Y un software bueno se hace con programadores buenos.

Es por eso que resalto en la importancia de esto: crear código legible y mantenible, es un paso más para crear software de calidad.