Estamos en el momento “sé verde” y, como programador, considero que es una buena oportunidad de tomar en consideración los aspectos “verdes” del área.
El compilador ignora los comentarios, mas no significa que deban ser ignorados por el programador. Sé parte de la ola documentando tu código; recordarás mejor tu trabajo, tendrás más amigos y estarás ayudando a crear código más verde, literalmente.
Hay un dicho en Inglés que dice “Always write and document your code as if the person who is going to maintain it is a serial killer and knows where you live“ que se puede traducir a algo como “Siempre escribe y documenta tu código como si la persona que lo va a mantener es un asesino en serie y sabe dónde vives”. Efectivamente, es una ladilla piedra en el zapato meterle mano mantener un código pobremente documentado y es probable que termines mentando madre teniendo una mala impresión de quien lo hizo.
Antes de un discurso moral y pintar escenarios utópicos de programación, quiero dejar algo bien claro a todo aquel que comienza en el área, y a quien ya tiene experiencia pues sirve para recordarlo: leer código poco documentado es la forma de aprender en el mundo real. Al cliente le importa que el código funcione y punto. Los estándares de desarrollo son iniciativa propia de cada programador y es nuestra responsabilidad como profesionales aplicarlo (bien sea luego de cada entrega o en cada nuevo ciclo de refactorización). Tener el entregable a tiempo es prioridad número uno. Entender y documentar un código que no escribiste, mejora tus aptitudes puesto que debes ejercer las funciones de compilador y correr en frío el código que quieres entender.
Hecha la aclaratoria de lo que es el mundo real, conocido también como calle mercado laboral; vamos a despotricar y dar lecciones de moral.
Algunas personas creen en el dicho “If it was hard writing it, it must be hard reading it“ (Si fue difícil escribirlo, debería ser difícil leerlo). Esto es reflejo de incompetencia y mediocridad. No se está considerando que en un futuro, es bastante probable que seas tú el que deba volver a leer ese código. Puede que pierdas tiempo valioso tratando de recordar lo que hace, en vez de concentrarte en mejorarlo/arreglarlo. Acción y reacción; así de sencillo y así de complicado.
Así de sencillo; porque documentar el código te hace ir a una capa de abstracción superior para definir de forma clara y concisa el proceso que realiza un bloque de código, y sirve de referencia en el futuro. Así de complicado; porque puede resultar fastidioso debido a que muchas veces es tomado a la ligera, porque hay otras cosas “más importantes” que hacer.
Así como existen normas de cortesía para la sociedad en general; documentar el código es, ciertamente, una de las mejores normas de cortesía en esta sociedad de programadores por cuanto ayuda a ubicar en contexto a quien lo lee por primera vez o, en todo caso, tener una referencia rápida sobre el bloque de código en cuestión.
Como nota adicional, hazte un favor y documenta el código a medida que vayas programando. Como dice Todd Hoff “Escribe los comentarios a medida que programas. No regresarás más tarde a documentar tu código. Simplemente no lo harás. No te mientas a ti mismo, al mundo ni a tu madre diciendo que lo harás”. Doy fe de ello. Mucho código “viejo” está en mi disco esperando ser documentado, y creo que así se quedará.
Es importante destacar lo significativo de ser auto explicativo. Documentar código comienza colocando nombres adecuados a las funciones y variables; nombres que sean de cierta forma naturales, evitando los acrónimos y contracciones. Esto puede ser todo un arte, pero el esfuerzo vale la pena.
Creo que las razones para documentar quedaron bien claras. Ahora queda hablar un poco del cómo. Pues sencillo, siguiendo patrones y estándares. Ni se te ocurra reinventar la rueda en este aspecto. Sé productivo y usa lo que ya está hecho y es ampliamente utilizado. Ejemplos (enlances en Inglés):
En mi experiencia, existen tres herramientas relevantes en la generación de documentación que siguen patrones ya establecidos y aceptados por la comunidad:
- Javadoc. Está basado en los estándares de documentación del API de Java y orientado a dicha tecnología, pero también es utilizado con otros lenguajes y herramientas.
- NDoc. Desarrollo en C# y .Net.
- Doxygen. Es un generador bien flexible que incluso acepta las convenciones utilizadas para Javadoc.
En este sentido, considero que es importante conocer y tener nociones básicas de las convenciones Javadoc; por ser, a juicio personal, las más utilizadas. Para respaldar esta aseveración, Eclipse, NetBeans y FlashDevelop son Editores/IDEs que manejan estas convenciones de manera bien amigable.
En conclusión; siempre habrá excusas para pasar por alto los comentarios, pero queda de nuestra parte el ser profesionales. Documenta el código a medida que lo echas escribes, haz lo humanamente posible por aprender y aplicar estándares y por último, recuerda que el escribir buena documentación comienza por ser auto explicativo.
/** * @author pctroll * * THE blog IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * Technorati token: NKVVWDWTSBAC */
Extracto, modificado, de la Licencia MIT.
Fotografía: Flavio Takemoto.
Excelente artículo, hermano!
Es así!
A Documentar se ha dicho, pues! Que para eso se ha inventado el Asterisco!
jejeje
¡Gracias Hector! Qué bueno tenerte por aquí apoyando uno de mis varios proyectos. Toda observación será bien recibida en pro de crecer.