Comentar o no comentar, he ahí la cuestión

Comentaban hace uno par de meses en esta entrada de GeekyTheory que en esto de poner explicaciones dentro del código había opiniones para todos los gustos. El autor decía que él pensaba que si necesitas comentar tu código es que no eres un buen programador. Partiendo del hecho de que comparto la afirmación de que tener que comentar cualquier parte del código es un mal síntoma, lo cierto es que no todo el código es algorítmico. Esto es, no todo son bucles, sentencias y llamadas a clases declaradas en los .h del proyecto. Hay muchas instancias de librerías externas que no son evidentes en su función y a simple vista, aparecen fragmentos de código que no se entienden sin estudiarse la librería o biblioteca en cuestión.

Ahora mismo ando enfrascado en un proyecto con muchos archivos que usa varias librerías grandes (Eigen, Boost, HDF5) y tenemos muchos archivos .h y .cpp describiendo distintas clases que se usan en distintas partes del código que es una simulación de física de plasmas. Bien. Resulta que queremos guardar los datos de la simulación en ciertos puntos por si el servidor donde ha de correr se cae o reinicia por las circunstancias que sea, y no perder el tiempo de calculo que se haya realizado. La idea es partir posteriormente de esos datos para continuar la simulación desde donde se interrumpió. Pues el código esta bien escrito, entre otras cosas porque no lo he escrito yo. Y no esta comentado. Y puedo asegurar que es terriblemente enrevesado. Os podéis imaginar, una clase que representa el campo eléctrico en diversos puntos de la “zona de simulación” se compone de un multi-array de la librería Boost que dentro contiene una lista doblemente enlazada en cuyos componentes contiene a su vez otra clase que representa planos de corte lateral (‘slices’ en 2D de la caja 3D de la simulación, para entendernos) que están subdivididos en distintos puntos. Estos puntos son en realidad vectores que representan el valor (ahora si, por fin) del campo eléctrico en cada uno de los puntos.

Suena enrevesado. Lo es. Se puede entender, tras mucho estudio del código y de la teoría (por suerte, soy físico y algo me ha ayudado) y llego a hacerme una idea bastante clara de lo que representa cada parte. Pero eso tras haber dedicado muchas horas a mirar el código, apuntar, anotar. Y eso es normal. El problema es que es una estructura tan compleja -pero bien diseñada- que es difícil mantener todo en la cabeza. Sobre todo, cuando tengo que pensar como transformar toda esa información que contiene en algo que se pueda guardar en un archivo HDF5. El caso es que al final, la interfaz de la clase es muy buena (hasta el momento, no he necesitado escribir ni una función extra), pero si el código estuviese comentado no tendría que repasarlo cada vez que quiero saber como obtengo la dimensión de una de las partes, o que indices debo pasarle a otra función para que trabaje con ello. Eso sin contar con los varios días que estuve estudiando a fondo el código para saber qué representaba cada elemento y como trabajar con ello.

Por lo anterior, no estoy de acuerdo con el articulo citado. Es cierto que, en la mayoría de los casos, si se escribe un código suficientemente bueno, claro y sencillo, no hay necesidad de añadir explicaciones. Pero en cuanto la tarea a realizar tiene una complejidad mayor, la cosa cambia. En esencia, creo que cuando se va a trabajar con muchas librerías externas, habría que comentar el código brevemente. Esto no es porque sea difícil de entender, ya que se supone que buscando en la documentación de la librería en cuestión, es fácil hacerse una idea de qué se está haciendo. El problema es que cuando otra persona ha de usar la interfaz de una clase que use extensivamente otras librerías -en este caso, HDF5, Boost y Eigen- no le queda más remedio que ir consultando la documentación de cada librería en cada momento que aparezca alguna utilidad de esa librería. Si estamos usando 3 librerías y todo eso dentro de alguna clase más o menos compleja, estamos hablando de llevar en la cabeza (o en notas en papel) la utilidad o funcionalidad de cada elemento de cada librería que se use dentro de la clase, aparte, claro está, de seguir el hilo de la clase en cuestión para saber exactamente qué es lo que hace o para qué sirve. Además del tiempo invertido en leer la documentación respectiva de cada librería.

Todo esto se soluciona añadiendo comentarios. Por muy perfecto o bien ordenado, claro y conciso, que sea el código, no tiene sentido que otro programador que tan sólo necesite saber cómo funciona la clase o qué hace exactamente -de cara a interactuar con ella o usarla directamente- tenga que recorrerse la clase entera, estudiar los manuales de las librerías y seguir el desarrollo del algoritmo (leyendo el .cpp en lugar de sólo el .h). Se desperdicia tiempo y esfuerzo. Con comentarios sencillos como “esta función guarda en disco manteniendo la estructura jerárquica” evitamos tener que bucear en la documentación para saber cómo se guarda en disco o cómo afecta ese comando al resultado.

Por esto, aunque el código que se escriba sea conciso, limpio, ordenado y lógico, los comentarios siguen siendo fundamentales. No es cuestión de comentar cada línea, pero sí de explicar qué hace cada clase, la interfaz que tiene y cómo se usaría. Supongo que al final, como todo, un buen término medio sería lo ideal.

Anuncios

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 )

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 )

Google+ photo

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

Conectando a %s