El buen uso de los comentarios en el código fuente

Como cualquier herramienta, los comentarios en el código fuente pueden ser una ayuda o una distracción. Estas son algunas ideas para tener conciencia de esto. Presentamos algunos ejemplos en Java, VB.NET y javascript.

Explican “por qué”

Los comentarios que nos explican por qué el código se programó de cierta manera sí son útiles.

por-que.PNG

Explican codigo confuso

Ayudan cuando el código fuente es confuso, especialmente cuando escribimos con una tecnología que no es muy legible. Lo mejor sería arreglar el código para que se pueda leer mejor. En este ejemplo en JavaScript, agradeceríamos un comentario que explique qué es “fn”, y porqué es importante saber que “existe”, o qué tipo de objeto es “t-grid t-refresh” por lo que debe estar oculto con “display none”. En ocasiones como esta, dominar la tecnología no es suficiente, pues necesitamos saber el por qué.

codigo-confuso

Explican código procedimental

En un código procedimental, los comentarios nos ayudan mucho pues un procedimiento tiende a ser extenso y con muchos detalles sin explicación.

procedimiento

Comentarios que no aportan

Usualmente los comentarios autogenerados no nos ayudan y hacen que el código sea mucho más extenso. Habrá casos donde sí es requerido llenarlos, pero usualmente podemos prescindir de ellos. Estos comentarios son una distracción.

redundantes

Comentarios de fechas y responsables

Si tenemos un sistema para controlar las versiones de los archivos, ya no es necesario llevar toda la historia de cambios en el mismo texto. Estos comentarios de historia son una distracción, aunque en el ejemplo siguiente la “Descripción” sí es util por ser algo muy técnico.

comentarios-de-fechas-y-responsables

Comentarios mentirosos

Un comentario que contradice lo que el código fuente hace es una gran distracción. Se debería borrar. En este ejemplo, el comentario dice que retorna True, pero el código retorna False. Estos comentarios son una distracción.

comentarios-mentirosos

 Código comentado

Un código fuente comentado es una distracción cuando el comentario contiene código antiguo. Es mejor borrarlo si ya no se usa.

codigo-no-se-usa

Dudas

Son una distracción cuando nos meten en duda. En este ejemplo, parece que el programador creó una lógica sin preguntar a un experto. Lo mejor habría sido que el programador preguntara y eliminara ese comentario. Ahora, nosotros no sabemos si ahí hay un defecto y tendremos que ir a preguntar (más trabajo, más tiempo).

duda

Son una distracción cuando dicen lo que ya leemos en el código. En este caso, podemos borrar el comentario.

obvio

No se entienden

Los comentarios deberían ser claros y concisos. Son una distracción cuando no se entienden. En este caso, no nos dice qué corregir ni ¡por qué!

no-se-entienden

Código sin terminar

Un comentario que explica que algo no está terminado ayuda cuando estamos desarrollando, pero es confuso cuando el código se quedó allí por descuido, como en este caso:

codigo-sin-terminar.PNG

Comentarios que dividen secciones en una clase

Cuando necesitamos colocar comentarios para separar métodos dentro de una clase, es una señal de que la clase es demasiado grande. Estos comentarios son una distracción. Deberíamos examinar la clase y dividirla en varias clases más pequeñas y con nombres más claros.

demasiado-grande

Las regiones

En línea de lo anterior, en .NET podemos crear regiones para agrupar separar bloques de código. En el siguiente ejemplo, las regiones son como comentarios que separan partes de esta clase de 400 líneas. Usar regiones en una clase es una clara señal de que contiene demasiada funcionalidad y es compleja. Esto dificulta la legibilidad y comprensión.

Deberíamos organizar sus funciones en namespaces y clases, no en un solo archivo de texto. Creemos clases pequeñas y enfocadas, que no requieran este tipo de divisiones.

regiones

Todo aporte es bienvenido. ¿Tiene algún otro ejemplo de un buen comentario o uno que distrae?

  • Agradecimientos a mis colegas Carlos Alvarez y Allan Huertas por sus aportes.

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión /  Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión /  Cambiar )

w

Conectando a %s