Documentación Eficaz de Código de Muestra para Programadores

En esta clase aprenderemos a documentar código de muestra de una manera legible. El objetivo es proporcionar calidad y coherencia en toda tu documentación, no funcionalidad. El código de muestra sirve como un mini-portal al contenido de una documentación completa.

Los programadores utilizan el código de muestra (como documentación) para iniciarse rápidamente en el uso de la herramienta y casi siempre navegan por el código antes de leer un tema en su totalidad. Debido a su especial consideración, el código de muestra requiere mucha atención.

Por otra parte, un bloque de código es una pieza de un código de muestra, posiblemente de una o unas pocas líneas, como la función que documentamos en una clase anterior. La documentación de bloques de código con el tiempo termina por difuminarse, ya que los equipos no suelen probar los bloques de código con el mismo rigor que los códigos de muestra completos, así que, por esta razón, nos enfocaremos más en este último concepto.

Creando un código de muestra correcto 🏄‍♂️

Un buen código de muestra es frecuentemente la mejor documentación para los programadores. No importa si los párrafos y listas de tu documentación son claros, los programadores prefieren mil veces un buen código de muestra. Después de todo, el texto y el código son lenguajes diferentes y es el código de muestra lo que en última instancia le importa al lector.

Al documentar código de muestra debemos de ser correctos y concisos para que nuestros lectores lo entiendan rápidamente y lo reutilicen fácilmente sin tener efectos secundarios. Para ello, el código de muestra debe cumplir las siguientes características:

• Estar programado sin errores.
• Realizar la función que dice realizar.
• Estar listo para producción (por ejemplo, el código no debe contener vulnerabilidades de seguridad).
• Seguir los formatos estándar del lenguaje de programación.

El código de muestra es una oportunidad para influir directamente en la forma en la que los programadores están escribiendo el código. Por lo tanto, el código establecerá parte de la calidad del software. Si eres programadora, considera los pros y contras en caso de que tengas más de una forma de programar una función. Codifica sobre la decisión que sea la mejor y la más legible.

Curso de Buenas Prácticas para Escritura de Código

Un bloque de código es una pieza de un código de muestra, posiblemente de una o unas pocas líneas de largo, como la función que documentamos en la clase "Documentando una función". La documentación de bloques de código con el tiempo termina por difuminarse porque los equipos no suelen probar los bloques de código con el mismo rigor que los códigos de muestra completos.

Averigua cuál es el caso primario de lo que el código de muestra debe hacer. Habla con los programadores y directores del proyecto, lee los requisitos y los comentarios del código.

Siempre prueba el código de muestra. Los sistemas adquieren mantenimiento, por lo que el código fuente puede cambiar sobre la marcha y el código muestra dejará de funcionar. Muchos equipos reciclan sus pruebas unitarias y los toman como código de muestra, eso es una mala idea. El objetivo principal de una prueba unitaria es probar; el único objetivo de un código de muestra es educar al usuario.

Código ejecutable 🚀

Cuando documentas el código de muestra debes explicar cómo ejecutarlo. Es posible que en el documento tengas que indicar a los usuarios que realicen actividades previas antes de ejecutar el código de muestra, como las siguientes:

• Descargar archivos.
• Instalar librerías.
• Ajustar los valores asignados a las variables.
• Configurar el entorno de desarrollo integrado (IDE).
• Ejecutar comandos.

Pero no siempre los usuarios realizan correctamente las actividades anteriores. En algunas situaciones los usuarios prefieren ejecutar código de muestra directamente antes que leer la documentación. Y justo cuando algo no les es comprensible, ahora sí, pasan a leer la documentación.

Esto me recuerda un estudio realizado por Acens, una empresa de tecnologías cloud, que muestra que el 75% de los usuarios reconoce que no lee el manual de instrucciones de los equipos y los dispositivos que adquieren hasta que se les atraviesa una falla.

Recuerda tomar capturas de pantalla del código en acción. Suelen ser útiles para dar a los lectores una idea del objetivo del código de muestra y de lo que la herramienta puede hacer.

Código conciso y comprensible 🤓

El código de la muestra debe ser conciso, lo ideal es que incluyas solo los componentes esenciales. El código irrelevante puede distraer y confundir a tu lector. Recuerda que esta sugerencia no es sinónimo para que los programadores o tú hagan malas prácticas para acortar el código.

Un código de muestra debe de ser comprensible, por lo que es importante contar con las siguientes características:

• Tener nombres descriptivos de clases, métodos, funciones y variables.
• Ser un código fácil de descifrar.
• En caso de que sea un código profundamente anidado, utilizar fuentes en negrita o de color para llamar la atención del lector sobre una sección específica del código de muestra.

Código comentado 📋

Considera las siguientes recomendaciones sobre los comentarios en el código de muestra:

• Mantén los comentarios cortos, anteponiendo la claridad a la brevedad.
• Evita escribir comentarios sobre código que es muy predecible en su descripción o, dicho de otra manera, que sea "bastante obvio". Siempre tomando en cuenta que en algunas ocasiones lo que para nosotros es obvio, quizás para alguien principiante no lo sea. Pensemos en nuestros lectores.
• Descarga toda tu energía escribiendo comentarios en puntos no intuitivos del código de muestra.
• Si tus lectores tienen mucha experiencia con una tecnología, no expliques lo que el código está haciendo, en este caso, explica por qué el código lo está haciendo.

En la medida de lo posible ten todo el código necesario en un solo bloque para que los lectores puedan copiar y pegar fácilmente. Ten en cuenta que este tipo de lectores no solo recogen el código, también cualquier comentario insertado.

Los comentarios dentro del código son un gran medio de comunicación técnica. Por lo tanto, pon cualquier descripción que pertenezca al código pegado dentro de los comentarios del código. Por el contrario, cuando tengas que explicar un concepto extenso o complicado pon el texto antes del programa de ejemplo.

Tal vez lo más importante es que te veas a ti mismo como el defensor o representante de aquellos desarrolladores que necesitan usar la API o la herramienta que estás ilustrando. Piensa en las preguntas que te harían si tuvieran acceso a las herramientas que tú usas y pon las respuestas en la documentación + el código de muestra.

Código reutilizable ♻️

Para que tu lector pueda reutilizar fácilmente el código de muestra solicita a las programadoras lo siguiente:

• Toda la información necesaria para ejecutar el código de muestra, incluyendo cualquier dependencia y configuración.
• Código que puede ser ampliado o personalizado de manera útil por otros usuarios.
• Tener un código de muestra fácil de entender, que sea conciso y que compile es un gran comienzo. Si truena la aplicación cuando el lector la esté ejecutando, no estará nada contento. Por lo tanto, cuando describas un código de muestra, ten en cuenta los posibles efectos secundarios. Nadie quiere un código inseguro o extremadamente ineficiente.

El ejemplo y el anti-ejemplo 🙅‍♂️

Además de mostrar a los lectores lo que deben hacer con el código de muestra, a veces es prudente mostrar a los lectores lo que NO deben hacer.

Por ejemplo, algunos lenguajes de programación permiten a los programadores poner punto y coma (;) al final de cada instrucción. Supongamos que estás escribiendo un tutorial en un lenguaje como JavaScript que no sugiere poner punto y coma al final de cada instrucción. En este caso, mostrar tanto un buen ejemplo como un anti-ejemplo beneficiará al lector. Por ejemplo:

Esta es una función válida con punto y coma al final de la instrucción.

console.log(getName());
function getName(){
   return  {
     name: "@davidenq"
   }
};

Y, en cambio, esta es una función inválida porque cuando ejecutemos el código obtendremos como resultado un error del tipo "Uncaught SyntaxError", cuando lo que esperamos como resultado es ‘@davidenq’.

console.log(getName());
function getName(){
   return  {
     name: "@davidenq";
   };
}

Código secuenciado 🧗‍♀️

Un buen conjunto de código de muestra puede incrementar el rango de complejidad de su lectura. Los lectores que no están familiarizados con cierta tecnología normalmente necesitan ejemplos simples para empezar.

El primer y más básico ejemplo en un conjunto de código de muestra se suele denominar "Hello, World!". Después de dominar lo básico, los programadores quieren ejemplos más retadores. Así que para que tu documentación sea un buen conjunto de código de muestra, proporciona una buena secuencia de códigos de muestra que vayan subiendo de nivel, desde simples, moderados hasta más complejos.

---

En el siguiente módulo aprenderemos cómo organizar nuestros documentos definiendo nuestro alcance y audiencia, dividiendo secciones y utilizando markdown para editar nuestro texto. :muscle: