Saltar al contenido

Artículos, tutoriales, trucos, curiosidades, reflexiones y links sobre programación web ASP.NET Core, MVC, Blazor, SignalR, Entity Framework, C#, Azure, Javascript... y lo que venga ;)

18 años online

el blog de José M. Aguilar

Inicio El autor Contactar

Artículos, tutoriales, trucos, curiosidades, reflexiones y links sobre programación web
ASP.NET Core, MVC, Blazor, SignalR, Entity Framework, C#, Azure, Javascript...

¡Microsoft MVP!
lunes, 3 de diciembre de 2007
Hace unos días publicaba una entrada donde hablaba de los problemas que generan la inclusión y el mantenimiento de comentarios en el código fuente de nuestras aplicaciones, aunque para no extenderme mucho sólo cité brevemente algunos aspectos a tener en cuenta a la hora de afrontar estos inconvenientes.

Ahora, partiendo de estos consejos, la abundante literatura que hay sobre el tema y mi propia experiencia, he creado los 13 consejos para comentar tu código, que contribuirán a hacerlo más inteligible y por tanto a incrementar su mantenibilidad a lo largo del tiempo.

1. Comenta a varios niveles

Comenta los distintos bloques de los que se compone tu código, aplicando un criterio uniforme y distinto para cada nivel. Puedes, por ejemplo, seguir un modelo como:
  • En cada clase, incluir una breve descripción, su autor y fecha de última modificación
  • Por cada método, una descripción de su objeto y funcionalidades, así como de los parámetros y resultados obtenidos
En realidad, lo importante es ceñirse a unas normas (comúnmente aceptadas si se trata de trabajo en equipo) y aplicarlas siempre. Las reglas concretas pueden ser elegidas a la conveniencia de cada cual.

Obviamente, una solución bastante aceptable e incluso aconsejable es utilizar las convenciones y herramientas (como XML en C# ó Javadoc para el mundo Java) que ayudan y facilitan esta tarea.

2. Usa párrafos comentados

Como complemento al punto anterior, es recomendable dividir un bloque de código extenso en "párrafos" que realicen una tarea simple, e introducir un comentario al principio de forma que se guíe al lector, precediéndolos, además, de una línea en blanco que ayude a separar cada uno del anterior.
  ...


// Comprobamos si todos los datos
// son correctos
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
...
}
}


// Ahora pasamos a realizar las
// transacciones
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
...

3. Tabula por igual los comentarios de líneas consecutivas

Si tenemos un bloque de líneas de código donde existe por cada una de ellas un comentario, es buena costumbre tabularlos todos a la misma posición, de forma que quedarán alineados y serán más sencillos de leer, sobre todo si forman parte de la misma frase.
  const MAX_ITEMS = 10; // Número máximo de paquetes
const MASK = 0x1F; // Máscara de bits TCP
 
Ojo a las tabulaciones. Hay editores que usan el carácter ASCII (9) y otros, en cambio, lo sustituyen por un número determinado de espacios, que suelen variar según las preferencias personales del desarrollador. Lo mejor es usar espacios simples o asegurarse de que esto es lo que hace el IDE correspondiente.

4. No insultes la inteligencia del lector

Debemos evitar comentarios absurdos como:
   if (a == 5)     // Si a vale cinco, ...
counter = 0; // ... ponemos el contador a cero
...
 
Este exceso necesita mucho tiempo a la hora de su creación, lo necesitará para su mantenimiento y, además, la mayoría de las veces distraerá al lector con detalles que no es necesario conocer o que pueden ser deducidos echando un vistazo al código.

5. Sé correcto

Evita comentarios del tipo "ahora compruebo que el estúpido usuario no haya introducido un número negativo", o "este parche corrije el efecto colateral producido por la patética implementación del inepto desarrollador inicial".

El uso de este tipo de comentarios no dice nada a favor de su creador, y, además, nunca se sabe quién los va a leer en el futuro. Emarts, en "Sapos, culebras y código fuente" muestra ejemplos de comentarios de este tipo.

Otro tema relacionado y, a mi entender, igualmente importante: cuida la ortografía. El hecho de que los comentarios no se vean desde el exterior no implican que puedas descuidarlos. Una ortografía correcta mejora la calidad de la expresión escrita y, por tanto, de la comunicación, que es de lo que se trata.

6. No pierdas el tiempo

No comentes si no es necesario, no escribas nada más que lo que necesites para transmitir la idea. Nada de diseños realizados a base de caracteres ASCII, ni florituras, ni chistes, ni poesías, ni chascarrillos.

En resumen, mantén los comentarios simples y directos, pues de lo contrario harás perder tiempo a tu sucesor. Para entender el efecto negativo de una verborrea excesiva, no hay como echar un vistazo a Hyperverbosity, publicado en Worse Than Failure hace unos días.

7. Utiliza un estilo consistente

Hay quien opina que los comentarios deberían ser escritos para que los entendieran no programadores. Otros, en cambio, piensan que debe servir de ayuda para desarrolladores exclusivamente.

En cualquier caso, coincidiendo con Ryan Campbell en su post Successful Strategies for Commenting Code, lo que importa es que siempre sea de la misma forma, orientados al mismo destinatario. Personalmente, dudo mucho que alguien de un perfil alejado a la programación vaya a acercarse al código, por lo que, para mi gusto, bastaría con cubrir el segundo caso de los expuestos anteriormente.

8. Para los comentarios internos usa marcas especiales


Y sobre todo, aunque no únicamente, cuando se trabaja en un equipo de programación en el que varias personas pueden estar tocando las mismas porciones de código. El ejemplo típico es el comentario TODO (to-do, por hacer), que describe funciones pendientes de implementar:
  int calcula(int x, int y)
{
// TODO: implementar los cálculos
return 0;
}
 
En este caso los comentarios no se usan para explicar una porción de código, sino para realizar anotaciones sobre el mismo a las que hay que prestar especial atención. Eso sí, si usas esta técnica, recuerda que debes actualizarlos conforme las anotaciones dejen de tener sentido.

9. Comenta mientras programas

Ve introduciendo los comentarios conforme vas codificando. No lo dejes para el final, puesto que entonces te costará más de el doble de tiempo, si es que llegas a hacerlo. Olvida las posturas "no tengo tiempo de comentar, voy muy apurado", "el proyecto va muy retrasado"... son simplemente excusas. Si tu intención es comentar el código, no te engañes y ¡hazlo!

Hay incluso quien opina que los comentarios que describen un bloque deberían escribirse antes de codificarlo, de forma que, en primer lugar, sirvan como referencia para saber qué es lo que hay que hacer y, segundo, que una vez codificado éstos queden como comentarios para la posteridad. Un ejemplo:

public void ProcesaPedido()
{
// Comprobar que hay material
// Comprobar que el cliente es válido
// Enviar la orden a almacén
// Generar factura
}

La codificación de cada una de las tareas descritas en el lenguaje correspondiente se realizaría justo debajo del comentario, quedando éste como encabezado de párrafo (como se describe en el consejo 2).

10. Comenta como si fuera para tí mismo. De hecho, lo es.

A la hora de comentar no pienses sólo en mantenimiento posterior, ni creas que es un regalo que dejas para la posteridad del que sólo obtendrá beneficios el desarrollador que en el futuro sea designado para corregir o mantener tu código.

En palabras del genial Phil Haack,
"tan pronto como una línea de código sale de la pantalla y volvemos a ella, estamos en modo mantenimiento de la misma"

Como consecuencia, nosotros mismos seremos los primeros beneficiaros (o víctimas) de nuestro buen (o mal) hacer.

11. Actualiza los comentarios a la vez que el código

De nada sirve comentar correctamente una porción de código si en cuanto éste es modificado no se actualizan también los comentarios. Ambos deben evolucionar paralelamente, pues de lo contrario estaremos haciendo más difícil la vida del desarrollador que tenga que mantener el software, al facilitarle pistas incorrectas para comprenderlo.

Atención especial a las refactorizaciones automáticas, que suelen introducir cambios en distintos puntos del código de un proyecto, dejando los comentarios obsoletos en ese mismo instante.

12. La regla de oro del código legible

He dejado para el final uno de los principios básicos para muchos desarrolladores: deja que tu código hable por sí mismo. Aunque se sospecha que este movimiento está liderado por programadores a los que no les gusta comentar su código ;-), es totalmente cierto que una codificación limpia puede hacer innecesaria la introducción de textos explicativos adicionales.

Recordemos, por ejemplo, el código introducido en el post "Interfaces fluidos (fluent interfaces)", donde se muestra lo que esta técnica puede aportar a la claridad y autoexplicación en un desarrollo:

Console.WriteLine("Resultado: " +
new Calculator()
.Set(0)
.Add(10)
.Multiply(2)
.Substract(4)
.Get()
);
 
A la vista del ejemplo, ¿es necesario añadir algún comentario para que se entienda qué hace el código? El uso de nombres apropiados (aconsejo leer el clásico Ottinger's Rules), indentación correcta y la adopción de guías de estilo (podéis ver algunas en la wikipedia, o googleando un poco) facilitan enormemente la escritura homogénea e inteligibilidad directa del código.

El no cumplimiento de esta regla hace que a veces los comentarios puedan parecer una forma de pedir perdón al desarrollador que se encargará del mantenimiento del software.

13. Difunde estas prácticas entre tus colegas

Obviamente, aunque ya hemos comentado en el punto 10 que nosostros mismos nos beneficiamos inmediatamente de las bondades de nuestro código comentado, la generalización y racionalización de los comentarios y la creación código inteligible nos favorecerá a todos, y sobre todo en contextos de trabajo en equipo. No dudes, por tanto, en crear cultura de comentarios en tu entorno.

Publicado en: Variable Not Found.

17 Comentarios:

Anónimo dijo...

buenisimo el articulo, si señor! Felicitancias al autor! }:)

Yo solo añadiria una cosa al punto 2 sobre los parrafos comentados: si empiezas a tener demasiados, mira si tienes que refactorizar el metodo! Cuando un metodo o funcion sobrepasa cierto numero de lineas, hay veces que por mucha explicacion que le des, quiere decir que se pasa de complejo

Pero vamos, que te ha quedado un articulo de quitarse el sombrero! }:D

Josepzin dijo...

En general me gustan todos los consejos, EXCEPTO! el de los TAB vs ESPACIOS... yo prefiero tener un codigo TAB, odio los espacios para dejar "espacios" :)

Anónimo dijo...

estupendo post, jose!

Anónimo dijo...

Enhorabuena por el artículo. Me parece un tema muy interesante, los comentarios son siempre "el patito feo" del código fuente, cuando en realidad son tan importantes como el resto.

Un saludo y gracias por tus reflexiones.

The Keeper Of The 7 Keys dijo...

El post está muy bueno, pero usar comentarios va en contra de mis principios... es más, una vez tuve una discusión con mi jefe porque yo nunca usaba comentarios y mi punto se vió reforzado por un post en el que decía "Un buen programador no necesita utilizar comentarios pues su código es claro y fácil de entender."

Desde entonces he adoptado esa política de no comentarios.

josé M. Aguilar dijo...

Gracias por los comentarios.

Keeper, el buen programador escribe código claro y limpio, eso es cierto. Sin embargo, no debes olvidar que los comentarios son parte del mismo, y sin son correctos, potencian esas características.

Es mi opinión, claro. :-)

Unknown dijo...

Muy buen artículo, respecto al punto 9, comparto la opinión de comentar antes de programar, es lo que todo programador debe hacer. No puedes lanzarte a programar sin saber lo que quieres lograr y que pasos debes dar para llegar.
No significa que debas sujetarte a esa estructura, en el camino seguramente surgirán otras etapas que no habías considerado.

Unknown dijo...

Felicidades por el artículo, al desarrollador por lo general no nos gusta "perder el tiempo" comentando y mucho menos documentando, como una buena metodología de análisis y diseño implica. Una de los hechos más importantes es que uno nunca sabe a quién le tocará dar mantenimiento a "nuestros códigos" y sobre todo con qué nivel viene, un buen comentario puede ayudar a reducir el tiempo invertido para entender, por lo que muchas veces al comentar código, pienso más en quién dará el mantenemiento a mis programas que en mi mismo. saludos a todos.

Anónimo dijo...

La verdad es que siendo algo tan necesario, pocas veces nos tomamos la molestia de hacerlo con la idea de ... "si lo he hecho yo, ya sabré porqué lo he hecho".

Y como siempre, el tiempo nos pone en nuestro lugar. Hay mucho codigo que en su momento me pareció genial y que al cabo de unas semanas ya no se para que lo hice de esa manera habiendo maneras más sencillas.

Unknown dijo...

Un bueno post. Me ha parecido genial. Un saludo.

a dijo...

Hoy lei en un blog esta frase creo que aplica para el posto
"Codifica siempre como si la persona que fuera a mantener tu código fuera un asesino en serie maníaco que sabe donde vives"

Anónimo dijo...

Muy buen artículo. Gracias.

Daniel Antokoletz Huerta dijo...

Soy programador desde hace treinta años. Dicen que mi código es muy compacto y sencillo, pero aprendí por el camino duro que si no documento el código, a los pocos días, luego de otras cientos de líneas de código más adelante, lo más seguro es que no sepa que cuernos quise hacer, o proqué lo hice.
Muy bueno el artículo.

Leidy Soany Falcón Monge dijo...

Excelente Artículo. Estaba buscando algo así para tener un punto de comparación con respecto a los comentarios. Buena iniciativa ;)

Anónimo dijo...

Aquí hay una visión completamente diferente y opuesta:

http://blog.svpino.com/2010/12/comentarios-no-no-y-no.html

Básicamente no a los comentarios.

Anónimo dijo...

Saludos, Gracias por difundir la importancia de comentar el código.

Te invito a participar de un comentario que recién realice en este foro:

http://www.muywindows.com/2011/08/20/windows-8-ya-no-tendra-que-competir-con-webos

Atte: Legion

Jorge Sánchez Fernández dijo...

Pasan los años y el tema de la carencia de buenos comentarios o la ausencia de los mismos siempre es un debate que esta presente. De los puntos que has expuesto mis preferidos son el 10 y el 12.
Yo primero intento que mi código sea lo suficientemente explicativo y después comento para mi, para entender el código en un futuro. Además añadiría otro punto que suelo seguir: no comentes que hace tu código, sino porque lo hace.

Saludos