28. Documentación del código: comentarios, nombres, README y documentación interna
28.1 Introducción
El código fuente también comunica. Sus nombres, estructura, comentarios, pruebas y archivos auxiliares forman parte de la documentación técnica del sistema. Un código difícil de leer aumenta el costo de mantenimiento, incluso si existen documentos externos.
La documentación del código no consiste en comentar cada línea. Consiste en hacer que el código sea comprensible mediante buenos nombres, estructura clara, comentarios útiles, README, guías internas y convenciones compartidas.
En este tema veremos cuándo comentar, cómo nombrar, qué debe incluir un README, cómo documentar módulos internos y cómo evitar documentación duplicada o desactualizada.
28.2 Código como documento
El código es la descripción ejecutable del sistema. A diferencia de otros documentos, define lo que realmente se ejecuta. Por eso, debe escribirse pensando en personas que lo leerán en el futuro: otros desarrolladores, revisores, mantenedores o incluso el propio autor meses después.
Un código claro reduce necesidad de comentarios explicativos. Si una función tiene buen nombre, parámetros comprensibles y responsabilidades acotadas, muchas explicaciones se vuelven innecesarias.
28.3 Elementos de la documentación del código
La imagen muestra elementos principales de la documentación del código: nombres claros, comentarios útiles, README, estructura de carpetas, convenciones, pruebas, ejemplos y documentación interna del módulo.
28.4 Nombres claros
Los nombres de variables, funciones, clases, módulos y archivos son una forma central de documentación. Un buen nombre comunica intención. Un mal nombre obliga a leer más código para entender qué representa.
Por ejemplo, calcularTurnosDisponibles comunica más que procesar. pacienteAutenticado comunica más que flag. Los nombres deben reflejar conceptos del dominio y responsabilidades reales.
La consistencia es clave. Si el dominio usa "turno", no conviene alternar sin motivo entre "cita", "reserva" y "appointment".
28.5 Comentarios útiles
Un comentario útil explica intención, motivo, restricción o advertencia que el código no comunica por sí solo. No debería repetir lo obvio. Un comentario como "incrementa contador" sobre una línea que incrementa un contador no aporta valor.
Los mejores comentarios suelen explicar por qué se hace algo, no solo qué se hace. Por ejemplo, pueden aclarar una decisión temporal, una restricción de un proveedor externo, una condición de compatibilidad o una regla de negocio poco evidente.
28.6 Comentarios peligrosos
Los comentarios pueden volverse peligrosos si quedan desactualizados. Un comentario incorrecto puede confundir más que la ausencia de comentario. Por eso, cada cambio de código debe revisar comentarios relacionados.
También son problemáticos los comentarios que justifican código confuso sin mejorarlo. Si una función necesita muchos comentarios para entenderse, quizá conviene dividirla, renombrarla o simplificarla.
28.7 README
El README suele ser la puerta de entrada a un proyecto o módulo. Debe permitir que una persona entienda qué es el proyecto, cómo ejecutarlo, cómo probarlo, cómo configurarlo y dónde encontrar más documentación.
Un buen README puede incluir propósito, requisitos, instalación, configuración, comandos frecuentes, estructura general, pruebas, despliegue local, enlaces a documentación y criterios para contribuir.
28.8 Documentación interna del módulo
Algunos módulos necesitan documentación interna propia. Puede ser un archivo README dentro de la carpeta del módulo, una explicación de diseño o una guía de uso interno.
Esta documentación es útil cuando el módulo tiene reglas complejas, contratos internos, dependencias importantes o patrones que deben respetarse al modificarlo.
28.9 Estructura de carpetas
La estructura de carpetas también comunica. Un proyecto bien organizado permite ubicar funcionalidades, pruebas, configuraciones, scripts y documentación con menor esfuerzo.
Cuando la estructura no es evidente, conviene documentarla. El README puede explicar qué contiene cada carpeta principal y qué criterios se usan para agregar nuevos archivos.
28.10 Convenciones de código
Las convenciones de código definen criterios compartidos: nombres, formato, organización, manejo de errores, estructura de pruebas, estilos de commits o patrones de diseño. Documentarlas reduce discusiones repetidas y mejora consistencia.
Muchas convenciones pueden automatizarse con linters, formateadores o revisiones. La documentación debe explicar el criterio y cómo ejecutar las herramientas.
28.11 Documentación generada
Algunas herramientas generan documentación a partir del código o anotaciones: referencias de APIs, documentación de clases, esquemas, contratos o comentarios estructurados. Esto puede ser útil si se mantiene cerca de la implementación.
Pero la documentación generada no siempre explica intención o decisiones. Puede listar métodos y parámetros, pero no necesariamente explicar por qué existen o cómo usarlos correctamente.
28.12 Pruebas como documentación
Las pruebas también documentan comportamiento esperado. Un test bien nombrado puede explicar una regla mejor que un comentario. Por ejemplo, una prueba llamada "no permite cancelar turnos dentro de las últimas 24 horas" comunica una regla funcional.
Para que las pruebas sirvan como documentación, deben ser legibles, estar bien organizadas y usar datos claros. Pruebas confusas o frágiles aportan poco como documentación.
28.13 Tabla de buenas prácticas
| Elemento | Buena práctica | Error común |
|---|---|---|
| Nombres | Expresar intención y dominio. | Usar nombres genéricos como data o aux. |
| Comentarios | Explicar motivo o restricción. | Repetir lo que el código ya dice. |
| README | Orientar instalación, ejecución y pruebas. | Dejar comandos desactualizados. |
| Pruebas | Nombrar escenarios esperados. | Usar nombres que no explican comportamiento. |
28.14 Qué no conviene documentar en el código
No todo debe ir como comentario. Reglas de negocio generales, decisiones de arquitectura, procedimientos de despliegue o manuales de usuario suelen pertenecer a otros documentos.
El código debe contener información cercana a la implementación. Si una explicación afecta a muchas partes del sistema o a varias audiencias, probablemente convenga ubicarla en documentación externa y enlazarla.
28.15 Mantenimiento
La documentación del código debe mantenerse junto con los cambios. Si se modifica una función, se revisan sus comentarios. Si cambia la forma de ejecutar el proyecto, se actualiza el README. Si cambia una convención, se actualiza la guía interna.
Una revisión de código puede incluir revisión de documentación asociada. Esto evita que la documentación cercana al código quede desfasada.
28.16 Errores frecuentes
Al documentar código suelen aparecer estos errores:
- Comentar cada línea en lugar de mejorar nombres y estructura.
- Escribir comentarios que repiten lo evidente.
- Dejar comentarios desactualizados.
- No mantener el README con comandos vigentes.
- No documentar módulos complejos cerca de su código.
- Usar nombres inconsistentes con el dominio.
- Olvidar que las pruebas también comunican comportamiento.
28.17 Qué debes recordar de este tema
- El código fuente también es una forma de documentación.
- Los nombres claros reducen necesidad de comentarios.
- Los comentarios deben explicar intención, motivo o restricciones.
- El README es la puerta de entrada al proyecto o módulo.
- La documentación interna debe estar cerca del código que describe.
- Las pruebas bien nombradas documentan comportamiento esperado.
- La documentación del código debe actualizarse con cada cambio relevante.
28.18 Conclusión
La documentación del código combina nombres, estructura, comentarios, README, convenciones y pruebas. Cuando estos elementos se cuidan, el sistema resulta más fácil de comprender y mantener.
En el próximo tema estudiaremos herramientas y formatos: Markdown, HTML, wikis, generadores estáticos y documentación como código.