Si eres un programador con varios años de experiencia, no tengo la más mínima duda de que alguna vez has tenido que pasar por el gran reto de descifrar cómo funciona el código que escribió alguien más.
Por otro lado, si justo estás comenzando tu trayectoria como desarrollador, espero que no tengas que pasar por el mismo desafío de quedarte atascado en un proyecto porque tienes que descifrar en qué estabas pensando en aquel momento y pensar porqué codificaste de la forma en que lo hiciste.
Ya sea que trabajes con un equipo o de manera independiente, documentar código mientras codeamos puede, por más increíble que suene, acelerar el proceso de construir una aplicación.
Aunque parece un proceso tedioso, afortunadamente existen métodos para documentar código que te harán la vida más sencilla.
Documentación de Código – Básica
Como todo en la vida, podría decirse que existen varios niveles de complejidad en la documentación de código. Para mí, existen tres cosas que son básicas cuando vas a documentar el código de una aplicación:
1. Cabeceras de clase
Son un bloque de comentarios (o comentario) de varias líneas que dan a conocer el objetivo general de una clase. ¿Qué representa esta clase? ¿Cuál es el propósito común de los métodos en ella?
2. Cabeceras de método o función
También son un bloque de comentarios (o comentario) de varias líneas que describen la funcionalidad de un método o función. Generalmente estos especifican cuáles son los parámetros que se reciben y, si es el caso, el valor que se regresa.
3. Líneas dentro de los métodos
Dentro de cada método o función, es muy útil agregar comentarios de una línea indicando qué es lo que se está haciendo. Esto puede servir para no perder el hilo de lo que se espera en cierto punto del código y poder averiguar dónde es necesario algún cambio.
En ambos tipos de cabeceras recomiendo utilizar las etiquetas que proveen la mayoría de los lenguajes de programación. Si no los conoces, recomiendo que los investigues, ya que pueden ser de mucha utilidad para estructurar y dar claridad a tus comentarios.
El código habla por sí mismo
El código puede ser complejo en su lógica, pero muchas veces se vuelve más fácil entenderlo si es descriptivo.
Esto significa que debemos darle nombres adecuados a los métodos y variables. Por ejemplo, si una función sirve para obtener el promedio de los valores en una estructura de datos, no lo llamemos metodoAlfa, mejor hay que optar por algo como obtenerPromedio.
Otro ejemplo es, si una variable sirve para almacenar el nombre de un usuario no la llames var1, llamémosla nombre o nombreCompleto. Esto permitirá que cualquier persona, incluyéndote a ti mismo, puedan interpretar fácilmente el código sin tener que memorizar todas las relaciones.
Mantén un estándar al documentar código
Cualquier comentario o forma de documentación que implementes en tu código debe tener consistencia, lo cual también puede llamarse estándar.
Asegúrate que todas las cabeceras sigan el mismo formato y contengan los mismos elementos, que cada bloque siga el mismo orden en sus componentes, y que todos los nombres de métodos y variables tengan el mismo formato. De esta manera será mucho más claro encontrar los elementos al momento de leer los comentarios.
Documentación de código – Avanzada
Todas las sugerencias anteriores son útiles en todo tipo de proyecto. Sin embargo, existen algunas recomendaciones para documentación de código un poco más exhaustiva y laboriosa que es increíblemente útil para algunos tipos de proyecto en específico, como creación de librerías, APIs, módulos, etc.
Cuando creamos este tipo de documentación, normalmente es con la intención de facilitar la vida de otras personas al permitirles reutilizar nuestro código. Pero, ¿cómo sabrán lo que hay disponible? Para ello deberás crear una guía o documentación de API.
Seguramente has utilizado de primera mano las referencias para algún lenguaje de programación como Java, Javascript, Python, HTML o CSS. En estas normalmente encuentras descripciones breves de los métodos, ejemplos cortos de cómo utilizar algún método (también conocidos como snippets), sugerencias y comentarios sobre versiones y obsolescencia.
A pesar de que puede requerir una gran cantidad de tiempo y puede ser un proceso muy tedioso, la inversión vale la pena. Simplificará bastante la utilización de la librería en cuestión y agilizará el desarrollo de nuevas herramientas.
Beneficios de una buena documentación
La mayoría de lo que te he mencionado hasta ahora es trabajo adicional a la creación de código. Sin embargo, no hay que verlo como un gasto de tiempo y dinero, sino como una inversión.
El tiempo que un programador invierte hoy en documentar correctamente un proyecto de desarrollo, le será de beneficio así mismo y a más de un programador en el futuro ¡Hoy por ti mañana por mi!
Algunos de los beneficios de documentar código que se pueden identificar en la práctica son:
- Ahorro de tiempo de desarrollo a mediano plazo
- Agilidad en el desarrollo
- Evitar creación de código duplicado
- Modularidad
- Escalabilidad
- Fácil identificación de errores
Esos son sólo algunos de los beneficios que en mi experiencia he notado que aporta la creación de una documentación de código adecuada. Estos mismos se traducen en ahorros monetarios para las empresas, por lo que, entre otras cosas, es importante aplicar estas buenas prácticas.
Conclusión
La documentación de código es un tema con el que todos tenemos sentimientos encontrados, ya que implica trabajo extra en el presente, mientras estamos bajo presión.
Sin embargo, hay que tomar en cuenta los beneficios que provee a mediano y largo plazo. Implementando medidas sencillas como desarrollar código descriptivo y agregar cabeceras a clases y métodos se puede obtener un beneficio sustancial.
En proyectos más avanzados es probable que se deba desarrollar herramientas de documentación más laboriosas, pero que al final agregan un valor tremendo.
Vacantes Recientes
Blogs Relacionados
