Escribir documentación para el código fuente puede ayudar a tu futuro yo y a tus colegas. Aprende a documentar JavaScript usando JSDoc.
¿Por qué documentar el código?
Supongamos que has escrito un par de funciones con JavaScript. Puedes usar esas funciones ahora mismo, o pasárselas a otro desarrollador.
Todo está claro en tu mente en el momento en que escribes el código, pero un mes después ya no recuerdas cómo usar la función A o la función B. Y lo mismo ocurre con tus compañeros. ¿Cómo se supone que se llama a la función A? ¿Qué parámetros toma? ¿Y qué forma deben tener los parámetros?
¿Cuántas formas hay de documentar el código?
Hay muchas formas de documentar un trozo de código. Por ejemplo, puedes escribir
- guías de cómo usar tu código
- un bonito README para el repo
- documentación del código en la fuente
Los tutoriales están bien porque puedes enseñar cosas a miles de personas, pero se quedan obsoletos pronto por muchas razones: falta de tiempo, cambios de última hora en el código.
Un README en el repo de Git es de esperar que esté más sincronizado con el proyecto porque cuando haces cambios en el código estás “obligado” a actualizar el README también (de lo contrario los usuarios se quejan).
Pero además de los howtos y READMEs, la documentación del código en la fuente tiene la mayor parte del valor. Se encuentra junto al código y ayuda a evitar errores al escribir código en el editor.
Hablando de JavaScript, podemos utilizar una capa de documentación llamada, JSDoc. Es una herramienta de línea de comandos y un “lenguaje de documentación” al mismo tiempo. Veamos cómo nos puede ayudar.
Primeros pasos
JSDoc es un bonito “lenguaje” para añadir documentación a JavaScript. Considera la siguiente función:
Esta función habla por sí misma, “getRecommendedProducts” después de todo es una frase descriptiva. ¿Pero qué pasa con el parámetro “id”? ¿Qué “id” debe ser realmente? Si miro el cuerpo de la función se hace evidente que “id” debe ser una variable, pero no se puede saber de qué tipo.
Por otro lado, “limit” es un poco más entendible, aunque no está claro si podría ser simplemente un número entero o algún otro tipo de dato.
Resulta que la documentación del código con anotaciones JSDoc puede ayudar a nuestras funciones a describir mejor sus intenciones.
Lo primero es saber cuál es la anatomía de una anotación JSDoc. JSDoc es tan simple como añadir un comentario antes de la función:
En este punto contamos con una pequeña descripción acerca de nuestra función, aunque esto se puede intuir fácilmente con solo ver el nombre de la función. Pero hagamos las cosas interesantes con anotaciones JSDoc para los parámetros de las funciones. Esta es la sintaxis:
Para cada parámetro se puede describir:
- su tipo, es decir, cadena, número, HTMLTableElement, objeto, etc.
- su nombre
- una descripción
Habiendo sentado las bases pasemos a documentar nuestra función.
Entrando en materia
“getRecommendedProducts” debe tomar una cadena de texto y un número entero como parámetros. Podemos añadir anotaciones para ambos de esta manera:
Añadir la documentación JSDoc tiene un efecto secundario. El autocompletado mejorará en tu IDE y obtendrás sugerencias en tiempo real.
Puede parecer una locura, pero añadir anotaciones JSDoc antes de escribir el código, no después, es otra cosa que puedes hacer. Y tiene dos buenos resultados. Primero, probablemente escribirás un código mejor y más simple debido a la idea que te formaste mientras escribías la documentación.
Además, elegirás mejores nombres para los parámetros, variables y funciones también.
Otras etiquetas
JSDoc tiene muchas más etiquetas. La anotación “author”, por ejemplo, es útil cuando se necesita saber qué persona elaboró el código. Aquí tienes un ejemplo:
Otra etiqueta útil es “return” (o “returns”) para describir el valor de retorno de una función. Aquí tenemos una función que retorna un objeto HTML:
JSDoc funciona muy bien cuando se especifican los tipos en el documento, pero también eres libre de omitirlos. Sin embargo, al hacerlo perderás todos los beneficios. ¿Así que eso es todo con JSDoc? Todavía no. Puede hacer otra cosa muy interesante. ¡Para saber de qué se trata, dirígete a la siguiente sección!
JavaScript con JSDoc: generar la documentación
JSDoc tiene un binario que puede ser instalado en tu proyecto JavaScript. Para hacer un poco de práctica crea un proyecto en una nueva carpeta e instala JSDoc:
Ahora, crea un nuevo archivo llamado example.js, aquí crearemos una clase de ejemplo con su respectivo constructor y métodos previamente documentados:
Finalmente, ejecuta JsDoc especificando la ruta de tu archivo:
Si todo salió bien, verás una nueva carpeta llamada “out” in la carpeta de tu proyecto. Dentro de dicha carpeta abre index.html y haz click en “Classes/API”, aquí podremos encontrar toda la documentación de nuestra clase:
Consideraciones finales
La documentación del código a menudo se pasa por alto y se considera (por muchos) más o menos una pérdida de tiempo. Te sugiero que no sigas los malos consejos. En su lugar, es preferible que adquieras el buen hábito de aprender a documentar el código en su etapa inicial.
“Un gran código debería hablar por sí mismo” dirán la mayoría de los desarrolladores. Y eso es cierto hasta cierto punto. El código debería ser claro, comprensible y en sencillo (ojalá fuera así de simple). En realidad, el código sigue siendo un lenguaje “de máquinas” y descifrar las instrucciones o funcionalidades simplemente mirando el código fuente sigue siendo un reto para la gran mayoría.
Escribir documentación para tu código puede ayudar a tu futuro yo y a tus colegas. Pero documentar tú código implica que tengas una gran autodisciplina.
Entonces, ¿es realmente tan difícil añadir documentación después de terminar un método o clase? Ahí es donde herramientas como JSDoc son útiles.
Mantente al tanto de
las novedades
Mantente al tanto de las novedades
