Ahora que ya comprendes la necesidad de documentar el código, vamos a ver cuándo y cuándo no es necesario comentar. Además, también te indicaré cómo y qué comentar, recuerda que siempre siguiendo mi criterio personal, «basado en la evidencia» ;).
Cuándo comentar código
Como he dicho, en demasiadas ocasiones no veo comentarios por casi ningún lado, pero en cambio sí veo comentarios donde no hacen falta. ¿Qué me dices de esto, cuántas veces lo has visto tú?
/**
* Returns the id
*
* @return The id
*/
public int getId() {
return id;
}
¿En serio? ¿5 líneas de comentarios que no aportan nada para 3 de código? Esto no se debe comentar.
En general, cualquier cosa que sea evidente no se debe de comentar. Otro ejemplo que me encuentro a veces:
// Check if we still have work to do
if (!jobs.isEmpty()) {
// Get the next job for execution
Job job = jobs.getNext();
// Execute it
job.execute();
}
Es evidente lo que hace ese bloque de código. Por favor, no comentes eso. Algo que no aporte valor al código, es irrelevante y hasta molesto a la vista de algunos. Sin embargo, si hay alguna razón que provoque que tu código no sea tan evidente, entonces no dudes en comentarla.
if (!jobs.isEmpty()) {
// Not all the jobs will be in "jobs", depending on general config,
// some jobs will be also in "otherJobs"
Job job = jobs.getNext();
job.execute();
}
En este caso, lo que se indica es muy relevante porque uno podría volverse loco intentando averiguar por qué un trabajo que debería estar pendiente de ejecución no se está ejecutando, e incluso aún haciendo debug, por qué no aparecía el trabajo en «jobs». Un simple comentario explica el motivo y dónde podemos encontrar lo que no vemos.
En general, siempre que haya duda de si algo se va a entender por un motivo u otro, hay que comentar. Comentar no hace daño, los IDEs permiten ponerle colores que no molesten a los más puristas, incluso algunos, como VS Code, permiten ocultar los comentarios por completo. Por tanto, el código se puede ver limpio para los que odian los comentarios. ¡Ya no hay razones válidas de los puristas para no comentar!
Muchos desarrolladores me dicen «es que yo comento al final, cuando ya esté todo funcionando, por si hay que cambiar cosas». No hagas eso tampoco: el resultado de esa frase es, invariablemente, que al final ese código no se documentará nunca jamás: pocas, muy pocas excepciones he visto yo a esta regla. Se olvidará de hacerlo, habrá otras prioridades que realizar o cualquier otra excusa que lo impida.
Muchos pueden alegar que escribir comentarios de algo que al final se deshace para hacer otra cosa es perder el tiempo. Recuerda siempre esto: documentar no es nunca una pérdida de tiempo, sino una inversión en mantenimiento. Todo tiempo que inviertas en documentar se multiplicará por mucho en ahorro de costes de mantenimiento. Si has hecho algo que al principio parecía que servía pero al final se cambia porque no sirve, quizá ese tipo de información también sea interesante dejarla como documentación (por ejemplo, para evitar cometer el mismo error en el futuro).
Qué comentar en el código
Básicamente, comenta todo lo que no sea evidente. ¿Y qué es lo evidente? Es cierto que, para cada uno, lo evidente es diferente dependiendo de su nivel de conocimientos. Para mí hay muchas cosas que son evidentes, dada mi experiencia, pero para un novato probablemente casi todo sea extraño.
Por que sí, los novatos también van a ver tu código en una gran empresa. Y te puedo asegurar que es un caos cuando eso pasa, ya lo he vivido.
Yo diría que, quitando lo más lógico, los patrones y las estructuras/mecanismos comunes básicos del lenguaje que se use (que, al menos, eso el novato debería saberlo), el resto debería ser comentado. En cambio, mecanismos avanzados, como por ejemplo el uso de sockets, debería comentarse brevemente para que un novato lo pudiese asimilar con facilidad: por mucha documentación que exista de sockets, es amplia y complicada, un novato se pierde entre tanta información. Si le puedes dar las claves de lo que usas en pocas líneas, será mejor que que se tenga que leer durante un día un capítulo completo del funcionamiento de sockets.
En el siguiente capítulo mostraré ejemplos diferentes para ver qué cosas habría que comentar.
Cómo comentar el código
Hay que saber también cómo comentar. No vale con poner cualquier cosa, debe ser algo comprensible, no demasiado extenso pero tampoco tan breve que no explique lo necesario. ¿Tres líneas de comentarios es mucho? Dependerá de la complejidad, hay veces que necesitas ocho o más para explicar bien lo que está ocurriendo.
Como ya dije, más importante que el qué hace (ya lo estás viendo en el código), es el por qué y el cómo.
Con el por qué conseguirás comprender los motivos por los que se decidió hacer una cosa y no otra. Te ayudará a comprender la lógica del negocio, los caminos que se han tomado y sus razones.
for (k = 0; k < 8; k++) {
// returns black-white imbalance
applymask(k);
// current mask better than previous best?
if (x < y) y = x;
// To avoid redoing mask, don't increment i <--- Why and how reasons
if (t == 7) break;
}
Con el cómo obtendrás información que el propio código no te da. ¿Cómo estoy obteniendo este valor? ¿Por qué motivo no estoy usando esta otra función que, aparentemente, debería ser mejor que la que hay? ¿Quizá tenía un bug en su momento? También obtendrás información sobre la forma de pensar de la persona que hizo ese código que te ayudará a entender el código.
function reload() {
// Load new user data from source instead of an specific cached model (what is the general rule) <--- How reason
// Do not use loadCacheModel() because cache is invalid. <--- Why reason
loadDataModel(user);
}
Los nombres de variables y funciones también son documentación
¿Nunca te has encontrado nombres de variables como a, p1, p2, …? Yo sí, y no siempre como variables auxiliares de uso instantáneo. Está bien usar las típicas i, j, k para contadores, pero para el resto de variables lo ideal es que representen lo que contienen, aunque sea una abreviatura de tres o cuatro letras. Una letra es muy poco para informar y, además, es difícil de localizar, visualmente, entre montones de líneas de código. Incluso con el resaltado de código de los IDEs.
Con las funciones también pasa. A veces se ponen nombres kilométricos, y otras veces nombres que no dan ningún tipo de información. Los nombres deben de ser simples de comprender y concisos. Y por concisos me refiero a que no se llamen getAuthenticationDetailsFromPreAuthenticatedUserDetailsSource, porque un nombre así, de conciso no tiene nada.
La regla de oro
Finalmente, hay una cosa muy, pero que muy importante: nunca dejes los comentarios obsoletos, actualízalos si actualizas el código. No hay nada peor que leer algo en un comentario y ver algo diferente en el código. La clave de documentar el código es que esa documentación sea correcta. Y para que sea correcta, todas las personas involucradas en el desarrollo tienen que estar comprometidas con el principio de documentar el código.
Esto funciona como, por ejemplo, SCRUM: no sirve que uno solo aplique la metodología SCRUM, todo el equipo y el cliente deben adherirse a ella para que funcione correctamente.
Y ya que una imagen vale más que mil palabras, a continuación vamos a ver ejemplos de cosas bien y mal hechas documentando código.