Documentar a varios niveles
Ya sé, ya sé: a nadie le gusta documentar. La documentación es eso que todos necesitamos pero nadie quiere hacer. Muchos hablan de las buenas documentaciones, otros critican las malas, y nadie las valora hasta que se necesitan.
Con base en mi experiencia que he tenido tanto en proyectos personales como en proyectos del mundo real, voy a enseñarte cómo documentar de tal forma que tanto tú como otros desarrolladores sean beneficiados.
Documenta a nivel de código
Supongamos que hoy vamos a hablar acerca del algoritmo de búsqueda binaria. Hablamos de cómo funciona, qué se hace y cuál es el resultado. Por alguna razón, decides que en este momento no lo vas a implementar, sino que lo dejarás para después.
Vuelves unas horas después para ver el algoritmo y al leerlo… ¡No recuerdas nada!
Vamos a intentar leerlo:
Si la derecha es mayor o igual que la izquierda, entonces obtenemos la mitad sumando la izquierda más… ¿la derecha menos la izquierda? Y eso lo dividimos entre 2 y lo truncamos. Luego, si el elemento medio del arreglo es igual al elemento buscado… ¿regresamos la mitad? Y si no, entonces… si el elemento del medio es mayor al elemento buscado… regresamos lo que sea que regrese
binarySearch()pero enviándole el arreglo, la izquierda… ¿el medio - 1? y el elemento que buscamos para que… ¿Para qué?
¡Es incomprensible! Aquí leer línea por línea no nos sirve de mucho.
Cuando vamos a explicar un algoritmo, es muy buena idea documentar el código a nivel de línea. Necesitamos añadir información adicional que sirva para entender el contexto de lo que queremos hacer. Ve el código ahora con comentarios:
Objetivo: permitirle a cualquier persona entender un algoritmo y que ésta haga el menor esfuerzo cognitivo posible.
Otro uso que se le puede dar a este tipo de documentación es para explicar alguna solución hacky: una solución forzada que después se cambiará a una solución adecuada.
Este tipo de documentación tienen un tiempo de vida muy corto. Normalmente son eliminados antes de poner en producción el código fuente. Si todos en el equipo de desarrollo consideran que ya no son necesarios, está bien eliminar dichos comentarios.
Documenta a nivel de función/método
Aprovechemos que estamos hablando de la búsqueda binaria para explicar el siguiente caso de documentación: supongamos que estamos diseñando una biblioteca que permite usar varios algoritmos de búsqueda como el de la búsqueda binaria. Los usuarios desarrolladores usarán nuestra biblioteca para resolver diferentes problemas.
Ellos descargan la biblioteca y cuando la intenten usar, verán lo siguiente:
Supongo que arr significa array, pero ¿L? ¿R? ¿X? ¿Qué regresa exactamente?
Nuestros usuarios podrían estar varios minutos ejecutando la función sin saber por qué ésta no funciona adecuadamente. Incluso podrían perder más tiempo metiéndose al código de la biblioteca para leer la implementación. Nosotros queremos que usen la función como si fuese una caja negra. Añadámosle comentarios:
Esto nos da el siguiente resultado en el IDE:
Objetivo: que cualquier usuario entienda cuáles son las entradas y salidas de las funciones o métodos, así como los requisitos para que la función o método cumplan su trabajo. Esto, para que el usuario no se preocupe por la implementación.
Otro buen uso que se le puede dar a este tipo de documentación es en las pruebas unitarias: muchas veces como programadores nos tocará escribir alguna prueba unitaria y este tipo de documentación aligera y agiliza la creación o revisión de una prueba.
Este tipo de documentación tiene un tiempo de vida más largo. No serán eliminados a menos que la propia función o método sea eliminado. Igualmente, el compilador o incluso el minificador utilizado eliminará estos comentarios al generar el código para producción.
Documenta a nivel de paquete
Aprovechemos de nuevo el ejemplo previo. Ya que tenemos una pequeña biblioteca que incluye el algoritmo de búsqueda binaria junto con otros más, podríamos publicarla en internet para que todos la puedan usar. La subimos a un repositorio de GitHub y listo.
Y cuando los usuarios lo encuentran, ven algo como esto:
¿Cómo lo instalo? ¿Tiene pruebas? ¿Tiene requerimientos? ¿Hay algún ejemplo de uso?
Sin siquiera una guía de instalación, es imposible saber cómo se usa esta biblioteca. Apenas una o dos personas de todas las que la vean intentarán descargarla e instalarla. Nosotros queremos que la biblioteca sea fácil de instalar, de integrar y de usar. Vamos a añadirle un README:
Objetivo: facilitar el uso y la instalación de nuestro paquete, biblioteca, componente, etc. para que cualquier usuario lo pueda integrar a su aplicación.
También si alguien que ve el repositorio no va a usar el paquete, el README le puede servir para entender qué hace sin que tenga que descargarlo. Incluso nosotros mismos podemos darle uso a un README: si queremos retomar un proyecto antiguo, el README nos puede ayudar a entender cómo se montaba o ejecutaba dicho proyecto.
Este tipo de documentación es vitalicia. Aunque el paquete se vuelva obsoleto, el propio README puede indicar esto y mostrar las razones por las que el proyecto se volvió obsoleto, así como alguna posible alternativa.
En resumen
Documentar es importante. No, corrección: documentar es indispensable. Cualquiera de estos tipos de documentación siempre será bienvenida y no solamente sirve para ayudar a los demás, también puede ayudarte a ti. Sí, documentar es cansado y tedioso, pero lo vale.
Seguramente al principio la documentación que hagas será redundante o poco descriptiva, pero te aseguro que con la práctica constante mejorarás y te olvidarás de estos problemas.
¡Gracias por leer el artículo! Sígueme en Twitter, GitHub o añádeme a LinkedIn.
Síguenos también en @GDGIPN, en nuestra página de Facebook y únete a nuestro grupo de Facebook.
