¿Qué es la documentación del código?

La documentación del código actúa como un mapa para quienes interactúan con una base de código, ayudándoles a navegar por lo que hace cada fragmento de código, cómo funciona, cómo usarlo y cómo encajan todos los fragmentos de código. Documentar el código ayuda a los equipos de desarrollo a mantener mejor el código fuente y, al mismo tiempo, guía a otras partes interesadas que puedan necesitar comprender y trabajar con el código, como analistas de ciberseguridad, científicos de datos, ingenieros de DevOps, gestores de productos y proyectos, ingenieros de control de calidad y redactores técnicos.

La documentación como código o "docs as code" trata la documentación como código de software. Este enfoque gestiona la documentación con las mismas herramientas que el código fuente: sistemas de control de versiones para revisar y hacer un seguimiento de los cambios, pruebas automatizadas para detectar problemas de formato y estilo, e integración/entrega continuas (CI/CD) para actualizar e implementar la documentación.

Aunque la documentación del código abarca la práctica más amplia de documentar el código, la documentación como código es una estrategia específica y un enfoque más técnico para escribir documentación.

La estructura de la documentación del código dependerá de quién sea el público y de cómo se vaya a utilizar. Estos son algunos tipos comunes de documentación:

• Documentación de bajo nivel
  
  
• Documentación de alto nivel
  
  
• Documentación interna
  
  
• Documentación externa

La documentación de bajo nivel suele hacer referencia a los comentarios en línea dentro del código. Como uno de los métodos más básicos para escribir documentación, estas anotaciones explican líneas o bloques de código particulares.

Las cadenas de documentación, o "docstrings", son otra técnica de documentación de bajo nivel. Aparecen antes de una definición de clase, función, método o módulo. Las docstrings tienen un formato estructurado que declara propósito, ejemplos de uso, funcionalidad, parámetros y valores de retorno.

Los comentarios en línea son más adecuados para especificar la lógica cuando no se puede deducir al examinar el propio código o para el código basado en algoritmos más complejos. Mientras tanto, se pueden extraer docstrings para la documentación de la interfaz de programación de aplicaciones (API) y proporcionar ayuda contextual dentro de los entornos de desarrollo integrados (IDE).

A diferencia de la documentación de bajo nivel que describe partes del código como entidades individuales, la documentación de alto nivel incluye detalles sobre su papel en el flujo de trabajo arquitectónico más amplio. Este tipo de documentación de software abarca diagramas de flujo y diagramas de lenguaje de modelado unificado (UML) que ilustran la arquitectura del código, documentos de diseño que describen la lógica empresarial y cómo el código se alinea con los requisitos del producto, y especificaciones de la estructura de bases de código o repositorios de código.

Esta documentación técnica es para uso interno dentro de una empresa. Los ejemplos incluyen convenciones de codificación, estándares y documentos de proceso sobre cómo los equipos desarrollan software. Las guías para configurar entornos de desarrollo también se incluyen en la documentación interna.

Esta documentación orientada al usuario está dirigida a desarrolladores y otros usuarios ajenos a la empresa. Por ejemplo, la documentación de la API establece las clases, funciones, métodos y módulos disponibles de las API públicas de un proyecto de software. La documentación externa también puede consistir en archivos de configuración, notas de integración y un archivo README.

El archivo README está escrito en Markdown, un lenguaje de marcado ligero para formatear texto sin formato. Contiene información sobre las características del proyecto, las dependencias, las instrucciones de instalación, los comandos de la interfaz de línea de comandos (CLI) y las opciones para obtener ayuda y soporte. Los proyectos de código abierto también incluyen información sobre las licencias y directrices para los colaboradores a la hora de enviar solicitudes de incorporación de cambios (pull requests), con el fin de integrar correcciones de errores o modificaciones del código en la rama principal del repositorio.

Escribir código de forma limpia y clara puede ser su propia forma de documentación. Sin embargo, una buena documentación sigue siendo esencial y ofrece estos beneficios:

• Mejora la colaboración

• Mejora la mantenibilidad

• Acelera el desarrollo de software

• Agiliza la incorporación

Un código bien documentado fomenta una mejor colaboración y comunicación dentro de los equipos de desarrollo. Los miembros pueden aprovechar la documentación del código como un lenguaje común para realizar reseñas de código, debatir cambios en el código y tomar decisiones en equipo.

La documentación facilita la refactorización del código, el mantenimiento y la optimización del rendimiento. Durante la depuración, los desarrolladores pueden utilizar la documentación del código como punto de referencia para encontrar errores de codificación y localizar su causa raíz.

Una buena documentación allana el camino para un desarrollo rápido, ahorrando tiempo en averiguar la funcionalidad del código y redirigiendo la atención a la aplicación de las actualizaciones de código adecuadas en su lugar. También ayuda a hacer un seguimiento de los cambios y a garantizar que los equipos puedan seguir el ritmo de una base de código que cambia con frecuencia.

La documentación del código ayuda a los nuevos miembros del equipo a aprender el funcionamiento interno de una base de código. Pueden familiarizarse más rápido con el diseño y la estructura del código, lo que les permite contribuir rápidamente al proyecto.

El código y la documentación trabajan mano a mano, por lo que también deben evolucionar juntos. Y algunas pautas para escribir código se aplican igualmente a la documentación. Estos son algunos consejos que pueden ayudar:

• A establecer estándares de documentación de código

• A integrar la documentación con la codificación

• La claridad y la concisión son la clave

• Con las decisiones de codificación de documentos 

• Mantenerlo todo actualizado

Al igual que las convenciones de codificación, también se deben seguir los estándares para la documentación del código. Estos estándares incluyen un formato coherente, como la sangría, los saltos de línea y el espaciado para la documentación de bajo nivel. Mientras tanto, las plantillas y las herramientas de documentación de código pueden ayudar con el estilo y la estructura de la documentación de las API y otra documentación externa y de alto nivel.

Esto podría implicar agregar cadenas de documentación al completar una función o insertar comentarios en línea mientras se implementan algoritmos o lógica intrincados. Escribir documentación mientras se programa puede ayudar a los desarrolladores a articular su proceso de pensamiento y sus decisiones, asegurándose de que los detalles cruciales no se pierdan por el camino. Puede que lleve algo más de tiempo al principio, pero puede convertirse en una parte natural del proceso de codificación y puede acelerar la depuración, la optimización y la refactorización en el futuro.

El exceso de documentación puede dificultar la legibilidad del código. Los desarrolladores deben priorizar la escritura de un código limpio y claro y, a continuación, añadir la documentación necesaria que se ajuste perfectamente a ese código.

En lo que respecta a la concisión, encontrar el equilibrio adecuado es vital. Por ejemplo, es posible que los fragmentos de código cortos y simples no necesiten documentación alguna. Por otro lado, los algoritmos más sofisticados requieren una documentación que explique la lógica subyacente de forma que los desarrolladores con distintos niveles de experiencia puedan entenderla.

Esto incluye el diseño, la arquitectura, la lógica y las opciones algorítmicas. Documentar estas decisiones de codificación, ya sea a través de un documento interno de alto nivel o una base de conocimientos compartida, ofrece contexto para cualquier cambio que se realice en el futuro.

Los equipos de desarrollo deben realizar reseñas y actualizaciones periódicas de la documentación de su código para asegurarse de que es precisa, completa y relevante, y refleja el estado actual del software. Incorporar documentación al proceso de revisión de código puede ayudar con actualizaciones periódicas.

La mayoría de los IDE tienen extensiones o complementos para generar documentación de código, pero otros marcos y herramientas también pueden ayudar a automatizar el proceso. Estos son algunos generadores de documentación comunes:

• Doxygen

• GitBook

• Javadoc

• JSDoc

• Sphinx

Doxygen soporta múltiples lenguajes de programación, como C, C++, Java, PHP y Python. Permite la representación en formato Markdown y puede generar documentación en formatos HTML, PDF y XML. Doxygen se puede personalizar a través de un archivo de configuración y proporciona la capacidad de generar diagramas que representan jerarquías visuales y correlaciones entre clases y funciones.

GitBook ofrece una interfaz de usuario para escribir y publicar documentación como sitio web, lo que puede hacer más eficiente crear tanto documentación interna como externa. La plataforma también tiene la característica de sincronización con repositorios de GitHub o GitLab.

La herramienta Javadoc analiza comentarios de documentación dentro del código fuente de Java para generar documentación de la API en formato HTML. Puede documentar clases, constructores, campos, interfaces y métodos.

Similar a Javadoc, JSDoc genera documentación de API para proyectos JavaScript. Su comunidad de código abierto ha desarrollado plantillas y herramientas para personalizar la documentación.

Sphinx está diseñado principalmente para Python, pero también se puede extender a otros lenguajes de programación. Soporta markdown y su propio lenguaje de marcado llamado reStructuredText. Sphinx puede crear documentación en varios formatos de output y cuenta con referencias cruzadas para vincular a otros elementos de código.

Los generadores de documentación se limitan a las anotaciones que encuentran en el código fuente. La IA generativa lleva la documentación un paso más allá, analizando un fragmento de código específico y añadiendo comentarios que describen su propósito y función. Muchos modelos de lenguaje de gran tamaño (LLM) para código tienen capacidades integradas para generar documentación.

Por ejemplo, IBM Bob puede generar líneas de comentario para un solo método o para todos los métodos dentro de una clase. Otras herramientas similares incluyen GitHub Copilot, JetBrains AI Assistant, Mintlify y Tabnine.

Como ocurre con cualquier sistema de inteligencia artificial, los desarrolladores deben revisar los resultados de las herramientas de documentación de código con IA para comprobar que sean completos y precisos.