Comentando el código

El código como transmisión de conocimiento

El código de una aplicación empresarial en cierta manera es una transmisión de conocimiento. Si lo miramos con detenimiento, nos cuenta qué cosas se hacen para resolver los problemas que se le plantean a la empresa, y cómo es su proceso de negocio o parte de él. De la misma manera que un libro, un documento, u otra manera de transmisión de conocimiento, se lee y se escribe.

¿Por qué comentamos el código?

A diferencia de un libro, el código no se escribe una sola vez, sino que se va leyendo y re-escribiendo constantemente, y por distintos autores. Un punto vital de nuestro trabajo como desarrolladores es transmitir hacia nuestros pares, superiores, y hasta a nuestro yo del futuro, el conocimiento inherente al código, para que no se pierda entre generaciones de personas y cambios de ownership.

Para lograr esta transmisión de conocimiento tenemos muchas maneras: una wiki, documentos compartidos, el historial de commits del versionador, etc, pero ninguna de ellas está tan cerca del código y el día a día del programador como los comentarios.

Los comentarios nos cuentan a nosotros mismos y a los que nos rodean cosas que no siempre podemos expresar en el código fuente, pero que necesitamos que estén al alcance del desarrollador que esté mirando dicho código, sin tener que moverse hacia otras fuentes.

Haciendo foco en lo que no se ve

Si bien el ejemplo es bastante exagerado, muchas veces nos encontramos con comentarios que prácticamente dicen lo mismo que la línea de código. Posiblemente esos comentarios no sumen demasiado, pero suman texto que hay que leer. Y un comentario que no aporta algo distinto a lo que dice el código, confunde más de lo que aclara. Con ver el código, ya podemos ver qué hace, o al menos, debería hacerlo. Si estamos forzados a escribir un comentario explicando qué hace el código, probablemente necesitemos re-pensar un poco nuestro diseño, y quizás obtengamos más ganancia haciendo eso que escribiendo un comentario. (este concepto no lo estamos inventando nosotros, sino que parte de algunos principios del libro “clean code”, el cual recomendamos leer)

Por otro lado, hay muchas cosas que no podemos reflejar en el código. Pensando en las preguntas anteriores, el por qué estamos haciendo algo, y para qué lo estamos haciendo, es lo que no podemos reflejar. Por más que nombremos bien los métodos, por mejor que sea nuestro diseño, no va a poder mostrar el contexto, las motivaciones, y todo aquel “background” que teníamos cuando lo estábamos escribiendo. Posiblemente sean esas las cosas que debamos apuntar como candidatos a comentario.

¿Y qué es lo que no estamos viendo?

Nos puede ayudar hacernos preguntas abiertas acerca del contexto, y ver qué cosas no podemos contar con el código. Algunas cosas que podemos pensar:

• ¿Para qué estamos yendo a determinado lugar?
• ¿Por qué elegimos hacerlo de esta manera, y no de otra?
• ¿Hay algún bug en la librería que estamos usando que nos obligue a ir por este camino?
• ¿Hay alguna legislación que nos obligue a hacer esto de una determinada manera?
• ¿De dónde podemos sacar más información?
• ¿Hay algún link útil que nos cuente de dónde sacamos esta solución?
• ¿Hay algo del proceso de negocio que no estemos contando en el código?

Las respuestas a este tipo de preguntas quizás nos aportan más valor, porque no las podemos deducir de la lectura del código, y quizás son los que deberíamos apuntar a escribir en forma de comentarios.

Arreglame, por favor!

El famoso //FIXME. Indica que hay algo del código que no hace lo que queremos, o que no lo hace de la manera que queremos. Hay distintas opiniones con respecto a este tipo de comentarios. Algunos consideran que son útiles, porque documentan los lugares a mejorar. Otros opinan que lo deberíamos arreglar en el momento, y que lo único que estamos haciendo es demorar la solución del problema.

Si vemos que arreglarlo nos lleva un tiempo considerable, o que preferimos no hacerlo en el momento, deberíamos dejar información suficiente para entender el contexto, ya sea con una explicación clara, o con una referencia a una documentación de qué es lo que falta hacer. También podríamos en ese momento generar una tarea en nuestra herramienta de gestión, que nos permita priorizar qué tan importante es con respecto a otras tareas que tenemos para hacer.

¿Y entonces?

Escribamos los comentarios de manera consciente y haciéndonos preguntas. Pensemos en que le estamos dando información a quien lea el código, y seguramente no vaya a tener el mismo conocimiento del contexto que tenemos nosotros. Veamos qué podemos aportar a esa persona para que lo ayude a entender mejor el código y el contexto. Aunque esa persona seamos nosotros mismos, dentro de algunos meses. Si tenemos todas esas cosas en mente, seguramente nuestros comentarios aporten valor y ayuden a tener una mejor aplicación.

Nota al pie

Una aclaración importante para los que trabajamos con Java: en este artículo no nos referimos a los Javadoc, que son un tipo específico de comentario, ya que al estar orientados a documentar el API y no la implementación en sí misma, tienen sus propios matices.