15. Documentación del Código
La documentación clara y actualizada es fundamental para mantener la calidad, facilidad de mantenimiento y comprensión del código por parte de cualquier miembro del equipo.
15.1 Objetivos
- Explicar el propósito, lógica y uso de cada componente
- Agilizar el onboarding de nuevos desarrolladores
- Servir como fuente de referencia para equipos técnicos y de QA
- Facilitar el soporte, mantenimiento y evolución del proyecto
15.2 Tipos de documentación
| Tipo | Propósito |
|---|---|
| Inline (en el código) | Explicación puntual del comportamiento lógico |
| KDoc | Documentación estructurada para clases y APIs |
| Documentación generada | Repositorio navegable generado con Dokka |
| Diagramas (UML, flujo) | Visión macro de arquitectura y relaciones |
15.3 Estándar de documentación en código
Utilizar KDoc para documentar clases, métodos y propiedades públicas. Ejemplo:
/**
* Caso de uso que obtiene la lista de usuarios activos
*
* @param repository fuente de datos
* @return lista de usuarios activos
*/
class ObtenerUsuariosActivosUseCase(
private val repository: UsuarioRepository
) {
suspend operator fun invoke(): List<Usuario> = repository.obtenerActivos()
}
15.4 Herramientas recomendadas
| Herramienta | Uso |
|---|---|
| Dokka | Generación automática de documentación (HTML) |
| Mermaid | Diagramas de flujo y arquitectura |
| Markdown | Documentación técnica, manuales, guías de uso |
| PlantUML | Diagramas UML, casos de uso, secuencia |
15.5 Configuración de Dokka
Agregar al build.gradle.kts:
plugins {
id("org.jetbrains.dokka") version "1.9.10"
}
tasks.dokkaHtml.configure {
outputDirectory.set(buildDir.resolve("dokka"))
}
Para generar:
./gradlew dokkaHtml
15.6 Buenas prácticas
✅ Documentar siempre clases públicas y métodos expuestos
✅ Usar lenguaje claro, conciso y técnico
✅ Mantener la documentación sincronizada con el código
✅ Versionar la documentación junto con el código
✅ Documentar decisiones técnicas clave
Una documentación bien mantenida es señal de un equipo maduro y organizado, y permite la evolución del software con menor fricción entre ciclos de desarrollo.