Cómo documentar una función de código

Ahora que tienes ubicados los conceptos básicos de programación, vamos a documentar una función. Una función normalmente cuenta con cada uno de los conceptos que vimos en una clase anterior: diferentes tipos de datos, variables y operadores.

¿Qué es una función? 📦

Una función es un conjunto de procedimientos encapsulados en un bloque de código, usualmente reciben parámetros, cuyos valores se utilizan para efectuar tareas específicas y adicionalmente retornan un valor.

Si eres programadora o technical writer, es importante saber documentar bloques de código. Esta actividad añade suficiente información para explicar lo que hace el código punto por punto, de forma que no solo las computadoras sepan qué hacer, sino que los humanos también lo entiendan (y por qué).

En el caso de las funciones, es vital documentarlas para saber cuál es la tarea que realizan, cuáles son los parámetros que reciben y qué es lo que nos devuelven.

Hay un mito que circula dentro del círculo de programadores: si tú escribes tu código claramente, usas una estructura apropiada y convenciones de nomenclatura adecuadas, con eso es suficiente para llamarle auto-documentación. Claramente no es cierto, solamente contribuye en gran medida a que el código sea fácil de leer, pero no significa que esté documentado.

Cada lenguaje de programación maneja diferentes estándares para documentar, en los ejemplos que hemos visto en este curso nos hemos basado en JavaScript, así que seguiré por esa línea.

JavaScript tiene un formato estándar para la documentación llamado JSDoc. Para el caso de las funciones te presento los siguientes formatos.

Comentarios multilínea en cabeceras de funciones 💆🏼‍♀️

Para comentar lo que hace una función usaremos comentarios de este tipo:

• El comentario comienza con una barra y dos asteriscos (/**).

• Cada nueva línea lleva un asterisco al comienzo (*).

• Escribe una descripción al principio para describir la función.

• La descripción de un parámetro se hace comenzando con @param.

• Si una línea es demasiado larga, la dividimos en varias líneas. La primera estará sin indentar y el resto indentada (desplazada hacia dentro) respecto a la primera.

• El comentario cierra con un asterisco y una barra diagonal (*/).

• Los comentarios puntuales sobre una línea de código se harán con dos barras inclinadas (//).

Si seguimos esa regla, la estructura quedaría así:

/**

* [algunaFuncion descripción]

* @param {[tipoDeDato]} nombredeParametro1 [descripción]

* @param {[tipoDeDato]} nombredeParametro2 [descripción]

* @return {[tipoDeDato]} [descripción]

*/

var algunaFuncion = function (nombredeParametro1, nombredeParametro2) {

// Hace algo...

};

Este es otro ejemplo de este mismo formato aplicado a una función real:

/**

* Agregar dos números y sumarlos

* @param {number} num1 El primer número

* @param {number} num2 El segundo número

* @return {number} El total de los dos números ingresados

*/

var sumarDosNumeros = function (num1, num2) {

return num1 + num2;

};

Usa etiquetas normalizadas 🕺

Cuando queramos agregar una descripción de un elemento usaremos etiquetas normalizadas. Por ejemplo, una etiqueta normalizada para describir un parámetro es @param. Siguiendo esa norma, tiene que escribirse tal cual, no puede ser normalizada si usamos @Parametro, @parametros o variaciones por el estilo.

Las etiquetas normalizadas más comunes son:

Sobre documentar vs. sub documentar: ¿añado información adicional? 👽

Usar el formato estándar JSDoc nos da una visión general de la función principal. Algunas veces con eso es suficiente, nuestra función sumarDosNumeros(), por ejemplo, está completamente descrita por el encabezado “Agregar dos números y sumarlos”.

Para funciones ligeramente más grandes es útil añadir comentarios de una línea (o a veces de varias) dentro de nuestra función para describir todo lo que está sucediendo.

Esto puede parecer exagerado para algunos programadores, pero tu yo del futuro siempre le agradecerá a tu yo del pasado por hacer esto cuando vuelvas a un proyecto que no has tocado en algún tiempo. Nunca te preguntarás qué hace una línea de código o por qué la escribiste. Definitivamente es preferible tener código sobre-documentado que sub-documentado.

Aquí un ejemplo de otra función, ¿podrías decirme qué dice cada línea?

/**

* Cambiar la visibilidad de una pestaña de contenido

* @param {string} selector Selector para el elemento

* @param {node} toggle El elemento que disparó la pestaña

*/

var toggleVisibility = function (selector, toggle) {

if (!selector) return;

var elem = document.querySelector(selector);

if (!elem) return;

elem.classList.add('active');

if (toggle) {

toggle.classList.add('active');

}

elem.focus()

if (document.activeElement.matches(selector)) return;

elem.setAttribute('tabindex', '-1');

elem.focus();

};

Si estás familiarizado con el código, quizás podrías entenderlo. Pero, si no, te tomaría algo de tiempo hacerlo. Aquí un ejemplo con algo de sobre-documentación:

/**

* Cambiar la visibilidad de una pestaña de contenido

* @param {string} selector Selector para el elemento

* @param {node} toggle El elemento que dispara la pestaña

*/

var toggleVisibility = function (selector, toggle) {

  

// Si no hay un selector, termina

if (!selector) return;

  

// Consigue que se muestre la pestaña

var elem = document.querySelector(selector);

if (!elem) return;

  

// Muestra el elemento

elem.classList.add('active');

  

// Si un elemento toggle fue dado, agrega un .active class para el estilo

if (toggle) {

toggle.classList.add('active');

}

  

// Trae el nuevo elemento dentro de focus

elem.focus()

  

// Si elem.focus() no funciona, agrega tabindex="-1" e intenta nuevamente

// (los elementos que no son focus por defecto necesitan una tabindex)

if (document.activeElement.matches(selector)) return;

elem.setAttribute('tabindex', '-1');

elem.focus();

  

};

---

En la próxima clase pondremos en práctica lo aprendido con algunos ejemplos, ejercicios y desafíos. ¡Allá te espero!