Lunes, diciembre 03, 2007

13 Consejos para comentar tu cdigo

Hace unos das publicaba una entrada donde hablaba de los problemas que generan la inclusin y el mantenimiento de comentarios en el cdigo fuente de nuestras aplicaciones, aunque para no extenderme mucho slo 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 cdigo, que contribuirn a hacerlo ms 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 cdigo, aplicando un criterio uniforme y distinto para cada nivel. Puedes, por ejemplo, seguir un modelo como: En cada clase, incluir una breve descripcin, su autor y fecha de ltima modificacin Por cada mtodo, una descripcin de su objeto y funcionalidades, as como de los parmetros y resultados obtenidos

En realidad, lo importante es ceirse a unas normas (comnmente 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 solucin 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 prrafos comentados Como complemento al punto anterior, es recomendable dividir un bloque de cdigo extenso en "prrafos" que realicen una tarea simple, e introducir un comentario al principio de forma que se gue al lector, precedindolos, adems, de una lnea 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 lneas consecutivas Si tenemos un bloque de lneas de cdigo donde existe por cada una de ellas un comentario, es buena costumbre tabularlos todos a la misma posicin, de forma que quedarn alineados y sern ms sencillos de leer, sobre todo si forman parte de la misma frase. const MAX_ITEMS = 10; // Nmero mximo de paquetes const MASK = 0x1F; // Mscara de bits TCP Ojo a las tabulaciones. Hay editores que usan el carcter ASCII (9) y otros, en cambio, lo sustituyen por un nmero determinado de espacios, que suelen variar segn 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 creacin, lo necesitar para su mantenimiento y, adems, la mayora de las veces distraer al lector con detalles que no es necesario conocer o que pueden ser deducidos echando un vistazo al cdigo. 5. S correcto Evita comentarios del tipo "ahora compruebo que el estpido usuario no haya introducido un nmero negativo", o "este parche corrije el efecto colateral producido por la pattica implementacin del inepto desarrollador inicial". El uso de este tipo de comentarios no dice nada a favor de su creador, y, adems, nunca se sabe quin los va a leer en el futuro. Emarts, en "Sapos, culebras y cdigo fuente" muestra ejemplos de comentarios de este tipo. Otro tema relacionado y, a mi entender, igualmente importante: cuida la ortografa. El hecho de que los comentarios no se vean desde el exterior no implican que puedas descuidarlos. Una ortografa correcta mejora la calidad de la expresin escrita y, por tanto, de la comunicacin, que es de lo que se trata. 6. No pierdas el tiempo No comentes si no es necesario, no escribas nada ms que lo que necesites para transmitir la idea. Nada de diseos realizados a base de caracteres ASCII, ni florituras, ni chistes, ni poesas, ni chascarrillos. En resumen, mantn los comentarios simples y directos, pues de lo contrario hars 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 das. 7. Utiliza un estilo consistente Hay quien opina que los comentarios deberan 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 programacin vaya a acercarse al cdigo, por lo que, para mi gusto, bastara 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 programacin en el que varias personas pueden estar tocando las mismas porciones de cdigo. El ejemplo tpico es el comentario TODO (to-do, por hacer), que describe funciones pendientes de implementar:
int calcula(int x, int y) { // TODO: implementar los clculos return 0; }

En este caso los comentarios no se usan para explicar una porcin de cdigo, sino para realizar anotaciones sobre el mismo a las que hay que prestar especial atencin. Eso s, si usas esta tcnica, 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 ms 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 intencin es comentar el cdigo, no te engaes y hazlo! Hay incluso quien opina que los comentarios que describen un bloque deberan 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 vlido // Enviar la orden a almacn // Generar factura }

La codificacin de cada una de las tareas descritas en el lenguaje correspondiente se realizara justo debajo del comentario, quedando ste como encabezado de prrafo (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 slo en mantenimiento posterior, ni creas que es un regalo que dejas para la posteridad del que slo obtendr beneficios el desarrollador que en el futuro sea designado para corregir o mantener tu cdigo. En palabras del genial Phil Haack, "tan pronto como una lnea de cdigo sale de la pantalla y volvemos a ella, estamos en modo mantenimiento de la misma"

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

11. Actualiza los comentarios a la vez que el cdigo De nada sirve comentar correctamente una porcin de cdigo si en cuanto ste es modificado no se actualizan tambin los comentarios. Ambos deben evolucionar paralelamente, pues de lo contrario estaremos haciendo ms difcil la vida del desarrollador que tenga que mantener el software, al facilitarle pistas incorrectas para comprenderlo. Atencin especial a las refactorizaciones automticas, que suelen introducir cambios en distintos puntos del cdigo de un proyecto, dejando los comentarios obsoletos en ese mismo instante. 12. La regla de oro del cdigo legible He dejado para el final uno de los principios bsicos para muchos desarrolladores: deja que tu cdigo hable por s mismo. Aunque se sospecha que este movimiento est liderado por programadores a los que no les gusta comentar su cdigo ;-), es totalmente cierto que una codificacin limpia puede hacer innecesaria la introduccin de textos explicativos adicionales. Recordemos, por ejemplo, el cdigo introducido en el post "Interfaces fluidos (fluent interfaces)", donde se muestra lo que esta tcnica puede aportar a la claridad y autoexplicacin en un desarrollo:
Console.WriteLine("Resultado: " + new Calculator() .Set(0) .Add(10) .Multiply(2) .Substract(4) .Get() );

A la vista del ejemplo, es necesario aadir algn comentario para que se entienda qu hace el cdigo? El uso de nombres apropiados (aconsejo leer el clsico Ottinger's Rules), indentacin correcta y la adopcin de guas de estilo (podis ver algunas en la wikipedia, o googleando un poco) facilitan enormemente la escritura homognea e inteligibilidad directa del cdigo. El no cumplimiento de esta regla hace que a veces los comentarios puedan parecer una forma de pedir perdn al desarrollador que se encargar del mantenimiento del software. 13. Difunde estas prcticas entre tus colegas Obviamente, aunque ya hemos comentado en el punto 10 que nosostros mismos nos beneficiamos inmediatamente de las bondades de nuestro cdigo comentado, la generalizacin y racionalizacin de los comentarios y la creacin cdigo 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. Publicado por Jos M. Aguilar a las 8:36 PM