Documentar código fuente. Esa mala práctica.

Documentar o no documentar código fuente. Ese es el eterno debate.

Para empezar a hablar os doy mi opinión. Documentar es una mala práctica extendida en el desarrollo de software.

¿Qué sentido tiene documentar el código fuente? Desde mi punto de vista, si el código está bien construido, muy poco. Puede servir para saber quién ha codificado un programa o una clase, o saber cuándo lo hizo o alguna otra cosa administrativa, pero desde luego no vale para lo que los supuestos expertos en calidad vienen pregonando, que es para aumentar la mantenibilidad del software.

La realidad es que el código se documenta para que la gente que no sabe de codificar tenga cierto conocimiento de para qué vale ese código. Y entonces me pregunto, si no sé programar, ¿qué gano sabiendo qué hace un programa? Quiero decir, ¿para qué voy a utilizar esa información? ¿Para leer el código? No creo. ¿Para hacer alguna modificación del código? Imposible. ¿Para controlar el trabajo de los programadores? Lo dudo.

Nada de eso. Exijo que el código se documente para no generar una dependencia del programador que lo ha codificado. Eso es lo que digo, pero ¿es cierto?

Muy bien. Si eso fuera cierto, preguntemos a un programador experto si le sirven los comentarios que ha escrito otro. La respuesta es que sólo le sirven si el código está mal construido y únicamente para saber qué es lo que tiene que hacer.

Vamos con un ejemplo de lo que es un código mal hecho.

public static void grijander003(ArrayList frifrilin, Random xxx) {

if(frifrinlin == null) { return; }

int xxy = frifrilin.Count; int xyxx = xxy+xxy+xxy

for(int yxx=xyxx;yxx

Object candemoreNOW = frifrilin[yxx];

frifrilin.RemoveAt(yxx);

…

} } }

¿Este código hay documentarlo? Claro; como incidencia o como ejemplo de lo que no hay que hacer. Si se documenta es porque es malo, porque el programador no ha seguido ningún criterio para nombrar variables, clases, métodos, identar, etc. Tenemos un mal programador que necesita ayuda aunque su código funcione.

Un programador que se precie de serlo habría escrito algo así como esto:

public static void gEnerarArrayAletarioPorLargoQueSeaElNombre(ArrayList elArray, Random numAleatorio) {

if(numAletario == null) { return; }

int contador = elArray.Count;

int triplecontador = contador * 3

for(int i=contador;i

Object temporal = elArray[i];

elArray.RemoveAt(i);

…

}

}

}

Este segundo código no necesita ninguna explicación ni ningún comentario. Habría que ver el resto, pero hasta lo que está escrito está clarito para qué vale y qué está haciendo. Si necesitas comentarios adicionales es que no sabes programar mucho.

De aquí deduzco lo siguiente:

1. Los buenos programadores no necesitan poner apenas comentarios en sus códigos fuente, y son capaces de leer otros códigos fuente de otros buenos programadores sin necesitar apenas comentarios.
2. Los malos programadores necesitan comentar su código porque es difícilmente inteligible. Un mal programador muy difícilmente va a ser capaz de leer otros códigos fuente de otros malos programadores, con o sin comentarios.
3. Los buenos programadores tienen dificultades para leer el código fuente de malos programadores. Lo leen más despacio; lo comprenden y lo acaban rehaciendo aunque sólo sea por una cuestión de amor propio.

Conclusión: dejemos de escribir comentarios y formemos buenos programadores.

Son los malos programadores los que pierden el tiempo:

1. Comentando su propio código. Si no lo comentan cuando lo hacen sino un día después, el tiempo dedicado a documentar se multiplica.
2. Corrigiendo errores de compilación, porque al ser malos, y tener un mal código, lo más probable es que tenga muchos fallos.
3. Haciéndoselo perder a los buenos programadores para entender el código, que lo acaban entendiendo, y para reescribirlo, que lo acaban reescribiendo.

Son los supuestos expertos en calidad de software los que pierden el tiempo:

1. Inventando todo tipo de formas de documentar código desconociendo cómo se programa.
2. Obligando a documentar el código fuente desconociendo que esto no tiene utilidad para los programadores.
3. Haciendo revisiones de código basadas entre otras cosas en los comentarios e indicadores de los comentarios.
4. Obligando a reescribir código por falta de un número dado de comentarios por línea de código (o cualquier otro indicador relacionado).

Conclusión: dejemos de exigir comentarios sin valor y exijamos buen código.

Tras todo esto, mi mensaje está claro. De forma general, documentar el código fuente es una mala práctica que nos hace perder tiempo a todos.