Documentar a la hora de programar

Documentar nuestro trabajo a la hora de programar es muy importante pues nos servirá para muchas cosas que ahora vamos a comentar.

La documentación de nuestro trabajo debe ser suficiente para que otros programadores puedan entenderla en caso de que la quieran usar o en el caso de que nosotros queramos utilizar ese trabajo posteriormente.

A la hora de programar podemos hacer aplicaciones tan complejas y extensas que pudiéramos llegar a tener problemas de entender cómo se hace cada cosa en cada momento y no entender nuestro propio código, por eso es muy importante que vayamos documentando todo lo que hagamos para que con un simple vistazo sepamos que hace cada parte del código y cómo lo hace y no tener que estar pensando cómo está eso ahí y porque.

Una buena documentación de una clase en Java debe incluir el nombre, un comentario que describa lo que hace la clase, también es útil poner que versión es, el nombre del autor o autores, documentar correctamente los constructores y los métodos incluyendo su nombre, lo que retornan, nombres y tipos de parámetros, descripción de lo que hacen, de los parámetros, de los valores que devuelven, etc. Haciéndolo así e incluyendo todos esos apartados en nuestros trabajos estaremos documentando correctamente nuestro trabajo facilitando así su posterior uso por nosotros o por otras personas.

Muchos programadores descuidan esta faceta y apenas comentan y documentan sus clases y trabajos y esto es una mala práctica que se debe evitar, pues si queremos usar las clases posteriormente en otros proyectos o si tenemos un proyecto muy grande es mejor tener todo bien documentando para saber cómo funciona con un simple vistazo y no tener que perder tiempo intentando entender que queríamos hacer con ese código en el momento que lo programamos.