Documentar el código

Creo que antes de seguir leyendo mi artículo, sería recomendable leer el siguiente: We Don’t Need That Documentation. Es un artículo escrito por Bozhidar Bozhanov, todo un gurú la programación Java, y publicado en Java Code Geeks.

La pregunta del siglo para muchos, sobretodo para los indecisos: ¿es necesario documentar el código? En mi opinión sí, al menos lo suficiente. Pero, ¿qué significa documentar el código? Documentar el código no es escribir páginas y páginas explicando qué hace tal clase, o tal método, o tal propiedad. Documentar es eso mismo, pero dentro del propio código. Esa definición mínima, de funcionalidad y atributos, que JavaDoc nos permite incorporar. Con eso es más que suficiente, si está bien hecho, para el programador, que de hecho es la única persona que se va a sumergir dentro del código.

Si viene el jefe de proyecto de turno y quiere esa documentación adicional, porque él no entiende el código, y porque él no va a meterse a estudiar ese código, que lo haga él mismo. Que se genere su propia documentación. Como bien dice Bozhanov en su artículo, es una pérdida de esfuerzo para el programador, y además cualquier programador podrá decirle al  jefe del proyecto para qué sirve y cómo funciona determinado fragmento del código. Pero lo que está claro es que no es tarea del programador crear esa documentación externa que ni siquiera va a utilizar nunca.

Es más, esa documentación externa tiende a quedar obsoleta con mucha rapidez. La documentación interna del código se va modificando cada vez que se agrega o se quita un parámetro, por norma general. La ayuda externa es posible que no se toque jamás, o casi nunca.

Para terminar, decir que hablo de la documentación, no del sistema de ayuda, o del manual de usuario de la aplicación. Tengo que estar de nuevo absolutamente de acuerdo con Bozhanov, y decir que esa ayuda es necesaria, y que por supuesto no debería escribirla un programador, sino más bien un usuario de la propia aplicación.

Por lo tanto, el día que se nos pida que documentemos, ya sabemos lo que decirle al QA de turno.