A punto he guardar esta entrada en la categoría documentales de este weblog, pero, no. Ha sido un lapsus de esos. Yo he venido aquí a hablar de... la importancia de la documentación del código fuente de nuestros proyectos.
¿De todos? Depende. ¿Para todos? Para ti. Sobre todo, para ti mismo. ¿No has escuchado aquello de que quien escribe lo hace en buena medida para él mismo? Pues así es. De Nietzsche aprendí que uno piensa con palabras, no con otra cosa, y, contra más palabras, mejor. No diré mejores pensamientos, pero, a lo menos la posibilidad de enterarse mejor de algo.
Claro que hay casos en los que el código fuente, prácticamente, y, si cuenta con buenos identificadores, se describe a sí mismo. Y, si el proyecto no es demasiado grande (pongamos unos cientos de archivos de por medio) es posible que uno lo tenga en la cabeza y la documentación haría más bien falta para otros.
Incluso en algunos proyectos más o menos grandes, pero, sobre los que has trabajado durante años, es posible que "la lógica" del asunto resida en tu cabeza, y, el código fuente, más o menos bien "identificado", puedes leerlo y "te lo sabes" más o menos, mejor o peor, sin necesidad de documentación, o por mejor decir, en base a la experiencia que tienes en el mismo.
Otras veces, sin embargo, cuando tocas palos nuevos, sobre todo, y no tienes muy claro que lo que estés haciendo esté bien hecho, o que no estés cometiendo algún error de bulto o menos importante, pero, error al fin y al cabo, que puede causar problemas, otras veces, digo, la documentación es importantísima.
No ya sólo para otros que pueden tener la necesidad o quieran darse el gusto de leer tu código fuente y tratar de entender "la lógica" del sistema, sino, como ya he dicho, documentar puede servirte a ti mismo, para hacerte una mejor idea acerca de lo que tú mismo estás llevando a cabo. Puede parecer una contradicción, pero, de Unamuno aprendí que acaso todo sea contradictorio. Eppurse move.
Sí. Es cierto. Uno escribe en buena medida para sí mismo, y uno documenta también para sí mismo. Ayuda aclarar cosas, y por el camino se descubren también cosas que no habías visto antes, aunque hubieras pasado al lado de ellas (nunca mejor dicho) en más de una ocasión. Pondré un ejemplo.
Ayer, o sea, hace un rato, antes de echarme a dormir y volver de despertar a la vida, descubrí en la clase "GbQuery" de Gesbit algo como esto:
if($EstaVariable == 0){
$EstaOtra = 0;
LuegoHagoEsto();
}else{
$EstaOtra = 0;
LuegoHagoEsto();
}
Y cosas como esas llaman la atención, pero, si no hubiera sido porque estaba documentado la clase, repasándola, mentalmente, a la vez que escribía, intentando aclarar una y otra vez para qué estaba donde estaba cada variable, cada condición, cada método, tuvo que llegar ese punto, para, luego de asegurar lo obvio, poner en orden ese código estúpido.
En fin... no es para tanto. Probablemente era un "error" (en realidad no es un error, sino una especie de "redundancia", pero, no iba a provocar problemas) que hubiera visto más adelante, pero, caí en el mismo mientras documentaba el método correspondiente, mientras repasaba cada una de sus instrucciones, mientras seguía "la lógica" del sistema, precisamente, para poder hacer lo que estaba haciendo.
Así que ya sabes, documenta, documenta y documenta. Aunque tampoco me hagas mucho caso, ¿eh? Yo no soy ningún gurú ni nada parecido. Y tú tienes todo el derecho del mundo a aprender, a criticar (hacer juicios), a poner en duda todo lo que te digan, incluido lo que yo te diga, no faltaba más.
Estoy probando 
