¿Qué sentido tiene documentar el código? ¿Es necesario? ¿No dicen algunos puristas que no es necesario documentar el código si está bien escrito? Resolvamos estas dudas brevemente, antes de comenzar.
Lo que dicen algunos puristas sobre el código y sus comentarios
Mucha gente defiende el código «lo más limpio posible», incluyendo esto el no llevar comentarios. Para ellos, el código debe ser auto-explicativo. Si no se entiende lo que hace, entonces hay que escribir mejor código que se explique por sí mismo.
En esta última parte estoy de acuerdo. El código debe ser claro en lo que hace, debe ser fácil de comprender. Por ejemplo, este código no necesita de explicación más allá de explicar para qué se ha creado (lo que se hace en la cabecera), está totalmente claro lo que hace:
// Get the default language for the app
export class LanguageService {
private supportedLanguages = ['es', 'en'];
private defaultLanguage = 'es';
constructor(public translate: TranslateService) {}
getLanguage(): string {
const userLanguage = this.translate.getBrowserLang();
return this.supportedLanguages.includes(userLanguage) ? userLanguage : this.defaultLanguage;
}
}
Pero si ya sabemos qué hace el código, ¿para qué queremos comentarlo?
La palabra clave aquí es qué. El problema es que nos faltan dos palabras clave más para entender todo el conjunto: cómo y por qué.
Te haré una pregunta: ¿cuándo fue la última vez que te dieron documentación actualizada y completa de un proyecto antes de que te pusieran a trabajar en él? Te contaré mi experiencia: a mí creo que una vez en toda mi carrera, y no porque haya colaborado en pocos proyectos.
Mantener documentación sobre cualquier proyecto que está vivo es sumamente complicado, porque hoy las aplicaciones no son como hace 40 años, con un propósito único, bien definido y que rara vez cambiaba. Por otro lado, creo que solo conozco a una persona que se lea decenas de folios de documentación de un proyecto antes de meterse a trabajar con él, y es mayor que yo. No, no es lo habitual.
El circuito habitual de un desarrollador al que contratan en pequeñas y grandes empresas (o al menos, las que he podido ver por dentro de mi mano y de mano de otros conocidos) es: te vamos a meter en el proyecto X, habla con John que te dará toda la información que necesites.
Luego hablas con John y te da algunas directrices, te acompaña el primer día para configurar el entorno, darte acceso a los archivos e indicarte tu cometido. A partir de ahí, te dan una tarea y… si tienes alguna duda, pregunta. ¿Documentación? Había una al principio, pero ya está obsoleta, mejor no la mires.
Bueno, ya estás en el lío, comienzas a ver el código de lo que tienes que modificar/ampliar y no entiendes nada. ¿Por qué llaman a esta función aquí y no allí? ¿Para qué es esta variable global de tres letras? ¿Cómo ha conseguido obtener este dato? Nada de esto está explicado en ningún lado. Y si el que lo hizo no comentó el código, entonces toca analizar el código paso a paso y ver qué va haciendo e intentar averiguar los porqués. Casi es una ingeniería inversa: llegar desde el código a las especificaciones detalladas.
Acabas de descubrir, por las malas, por qué debemos documentar el código fuente. Nadie va a leer la documentación fuera del código. Pero el código lo van a ver todos los que tengan que modificarlo. Además, siempre será código actualizado, por lo que es importante que los comentarios también lo sean. Si tu código está documentado:
- Podrás recordar cómo funcionaba tu código mucho tiempo después de haberlo creado.
- Otro podrá saber qué hace tu código y por qué, sin tener que descifrarlo.
- Podrás saber qué hace un bloque de código complejo sin tener que analizar ni una línea, simplemente leyéndolo en los comentarios.
- Podrás averiguar por qué no se usó una característica concreta que hoy usarías (¿quizá tenía un bug en su momento?).
- Podrás descartar otras soluciones que ya se probaron antes pero que daban problemas (quizá parecían evidentes al principio pero al tenían algún inconveniente).
¿Entonces es necesario documentar el código?
Si quieres poder mantener el programa sin volverte loco en el futuro (o que se vuelvan los demás), definitivamente sí.