Hola, desarrollador. Me alegro de que hayas llegado hasta aquí, por un azar del destino quizá. Quiero iniciar un movimiento, el movimiento «CodeDoc» para documentar código fuente de forma correcta y que el código sea más sano. Y me gustaría que te unieses a él.
Antes de nada quiero dejar una cosa clara: aquí voy a exponer una guía que, a día de hoy (enero 2021), es una opinión personal. No pretendo sentar cátedra, pero sí creo que mi enfoque puede ayudar a otros desarrolladores.
Como casi todo en esta vida, hay más formas de entender las cosas, además de la que uno mismo tiene. Dicho esto, ésta es mi visión de un tema que, por mi larga experiencia en el sector (25 años a fecha de publicar esto), sigue siendo el gran olvidado de los desarrolladores, sobre todo los más jóvenes. Si quieres aportar tus ideas, contacta conmigo y las discutiremos para añadirlas.
«Basado en la evidencia»
Bueno, basado en mí evidencia. 25 años programando de forma profesional dan para muchas experiencias y, tras estos años, es evidente que algo he aprendido: documentar el código es fundamental. Sí, no digo interesante, ni digo importante, digo fundamental. Cada año llegan nuevas generaciones y sigo viendo lo mismo ahora que hace 20 años: cien líneas de código y uno o dos comentarios irrelevantes. Eso no es mantenible. Debemos acostumbrar a las nuevas generaciones a que documenten bien. ¡Difunde el movimiento!
Los desarrolladores, esos seres extraños
Somos apasionados, somos inteligentes, somos curiosos, pero lo que no somos es proclives a dar explicaciones detalladas. Nos cuesta documentar, es una realidad. Tan solo tienes que abrir cualquier proyecto de GitHub y verás que los comentarios en el código brillan por su ausencia y que la documentación principal suele ser, como poco, escueta. Hay excepciones claro, pero son eso, excepciones.
Es hora de que cambiemos eso. No importa si eres uno solo trabajando o participas en proyectos con decenas de compañeros, documentar (o si prefieres el término, comentar) los pequeños trozos de código que hacen maravillas es imprescindible para el futuro mantenimiento de ese proyecto.
Porque lo que hoy acabas de hacer y te ha llevado dos horas resolver por su complejidad, que luego has refactorizado y al final te ha quedado en diez hermosas y poderosas líneas de código, eso lo recuerdas perfectamente mañana, la semana próxima y el mes próximo. Pero un año después necesitarás modificar el diseño y no sabrás porqué lo hiciste así. Es más, no sabrás ni qué hacen esas extravagantes soluciones que aplicaste y tendrás que analizar paso a paso lo que hace ese avanzado diseño de solo diez líneas. Y pasarás 15 o 30 minutos intentando entender aquello que hiciste. Y, será entonces, cuando te darás cuenta de que deberías haber documentado esto, para no tener que perder el tiempo ahora.
Y eso si el código lo hiciste tú. Ahora imagina qué pasará cuando otro recoja tu código (o tú el de otra persona) y se pase 30 o 60 minutos analizando qué maquiavélica mente diseñó semejante solución en solo diez líneas de código.
Documentar es sencillo, si sabes cómo hacerlo
En los siguientes capítulos te voy a dar las claves para documentar tu código de forma eficaz. Te mostraré ejemplos reales (código fuente en producción) de código correctamente comentado y ejemplos de todo lo contrario. Es la misma solución que llevo aplicando 24 años con total éxito (sí, el primer año yo tampoco documentaba, hasta que comprendí su importancia). Te puedo decir, por ejemplo, que las empresas a las que les desarrollé software a medida en el año 1998 siguen, a día de hoy, usando mis programas y solicitándome cambios y mejoras. Y si soy capaz de realizarlos rápidamente y sin romper nada es, sencillamente, porque todo, absolutamente todo mi código, está comentado.
Documentar es automático, si lo incorporas a tu rutina
Nos cuesta empezar, sí. Pero somos seres de costumbres. Es como pasar de un lenguaje cuyas instrucciones terminan sin más (como Python) a otro en el que tienen que acabar en «;» (como Java). Al principio te cuesta acostumbrarte, pero la repetición hace que se incorpore a tu forma de trabajar automáticamente, sin que te des cuenta.
Yo ni siquiera estoy pensando que estoy comentando el código. En cuanto termino un bloque de código algo complejo de comprender, automáticamente estoy escribiendo sus comentarios. Estoy poniendo mi «;» para terminar «la línea».
Te invito a que unas al movimiento y descubras cómo documentar tu código correctamente y cuándo no hacerlo. Lee los siguientes breves capítulos.