Documentar código es una de las actividades menos sexy del proceso de desarrollo de software. Sin embargo, con el tiempo este hábito acelerará tu proceso de aprendizaje y de trabajo en tus proyectos de software. De hecho, ayuda a prevenir y detectar errores en el código.
Por documentar código se entiende el añadir información pertinente cercana a cada instrucción o bloque de instrucciones de un programa, usando los símbolos correspondientes para insertar comentarios del lenguaje de programación utilizado, con el propósito de explicar qué hace y cómo hace cada una de sus funcionalidades. El mejor código es el que se explica a sí mismo, es decir, el que necesita poca o casi ninguna documentación. Por otro lado, toda documentación debe ser actualizada con cada modificación o evolución del código.
No importa si formas parte de un equipo de desarrollo o si trabajas por tu cuenta, el documentar tu código te ayudará enormemente en tus proyectos futuros de construcción de sistemas software por las siguientes 5 razones:
1. Documentar tu código te ayudará a entender tu propio trabajo
Los comentarios a lo interno del código permiten comprender más rápidamente el propósito o la intención de un bloque de instrucciones, e incluso de líneas complejas y oscuras, que hayas escrito tiempo atrás. Así, evitarás perder ese valioso recurso al tener que descifrar o tratar de recordar por qué codificaste algo de la forma en que lo hiciste.
2. Documentar tu código ayudará a los demás a entenderlo mejor
Si perteneces a un equipo de desarrollo donde el código debe compartirse con otros programadores, estarías ayudándoles mucho más si está debidamente documentado. Ellos ya no tendrán que acudir a ti frecuentemente a preguntarte cómo o por qué hiciste algo de la forma como lo hiciste, sino que ahora simplemente leerán tu documentación y continuarán su camino. Así, tanto ellos como tú mismo ahorrarán tiempo valioso que podrán invertir en tareas más importantes.
3. Documentar tu código te ayudará a corregirlo más fácilmente
El código documentado permite saber exactamente cuál es y dónde está la funcionalidad o el bloque de instrucciones que están causando problemas en tu aplicación, evitando diluirte en áridas revisiones secuenciales o aleatorias, permitiéndote corregir más fácil y rápidamente los errores detectados.
4. Documentar tu código permitirá mantener claro su objetivo
Describir verbalmente la intención del código ayuda a recordar las razones de por qué fue escrito, su propósito, facilitando la comprensión de su existencia. Si un trozo de código tiene una particular importancia, corrige potenciales errores durante la entrada, proceso o salida de datos, o se escribió con fines de prueba, su documentación te lo informará con claridad y efectividad.
5. Documentar tu código lo volverá más fácilmente reutilizable
A medida que programamos es posible que necesitemos repetir algo que ya antes hemos construido. En lugar de empezar a ver todo tu código, línea por línea o bloque por bloque buscando lo que te interesa, podrás acudir a su documentación para encontrarlo con mayor eficiencia.
En conclusión, documentar tu código te servirá para entenderlo, encontrarlo y corregirlo con mayor facilidad, y te permitirá ahorrar tiempo tanto a ti mismo como a quienes necesiten revisarlo y reutilizarlo. Es una buena práctica a adoptar, tanto de manera personal como grupalmente.
Espero que este post te ayude muchísimo en tu formación y crecimiento como programador como me ha ayudado a mí. Si sabes de otras razones que valga la pena incluir en este post, házmelo saber. No olvides dejar tu comentario y compartir el post con quienes consideres que pueda serle útil. Si encuentras algún link roto o vídeo que no aparece, por favor avísame para corregirlo.
Comentarios
Publicar un comentario