Documentación en Swift: cómo escribir código que habla por sí mismo

Entrenador de Python en Línea para Principiantes

Aprende Python fácilmente sin sobrecargarte de teoría. Resuelve tareas prácticas con verificación automática, recibe pistas y escribe código directamente en el navegador, sin instalar nada.

Start Course

Por qué la documentación es un superpoder del desarrollador

Imagina: abres un proyecto ajeno en Swift seis meses después de haber sido escrito. El código funciona, pero entender por qué el autor hizo exactamente eso y no otra cosa es imposible. No hay comentarios, los nombres de las variables son del estilo a1, temp2. ¿Te suena familiar?

Una buena documentación no es solo un gesto de cortesía hacia tu yo futuro. Es una herramienta que ahorra horas de depuración, acelera la incorporación de nuevos desarrolladores y transforma el caos en un sistema ordenado. En este artículo, analizaremos las mejores prácticas para documentar código Swift, desde comentarios básicos hasta DocC avanzado.

Fundamentos: de comentarios simples a descripciones significativas

//, /// y /* */ — cuándo usar cada uno

En Swift hay tres tipos de comentarios, y cada uno tiene su propósito:

Comentarios de una línea // — para notas rápidas, TODO o desactivaciones temporales de código. No abuses: si el comentario explica lo obvio, es innecesario.
Comentarios multilínea /* */ — para bloques de explicación o para desactivar secciones enteras de código durante la depuración.
Comentarios de documentación /// — son tu herramienta principal. Xcode los captura automáticamente y los muestra en Quick Help.

/// Calcula el área de un círculo dado su radio./// - Parameter radius: Radio del círculo en metros./// - Returns: Área en metros cuadrados./// - Throws: `InvalidInputError.negativeRadius` si radius < 0.func areaOfCircle(radius: Double) throws -> Double {    guard radius >= 0 else {        throw InvalidInputError.negativeRadius    }    return Double.pi * radius * radius}

Comentario malo vs comentario bueno

Compara dos enfoques:

// MALO: Comentario obvio// Incrementamos el contador en 1counter += 1

// BUENO: Explica el "por qué"// Usamos incremento porque esta es una sección crítica// de rendimiento y la operación ++ está obsoleta en Swiftcounter += 1

La regla de oro: un comentario debe responder a la pregunta «por qué», no «qué» hace el código. El código en sí mismo debe ser legible para que el «qué» se entienda sin palabras.

DocC — documentación de nueva generación

Qué es DocC y por qué es imprescindible

Con la llegada de Xcode 13, Apple presentó DocC (Documentation Compiler), una herramienta que convierte tus comentarios /// en documentación hermosa e interactiva directamente dentro de Xcode y en la web. Se acabaron los archivos PDF y las páginas wiki que se quedan obsoletas en una semana.

Cómo usar DocC en un proyecto

Configuración: En Xcode, selecciona Product → Build Documentation. DocC recopilará automáticamente todos los símbolos documentados.
Enlaces dentro de la documentación: Usa `` para enlazar a otros tipos:

/// Usa ``NetworkManager`` para enviar solicitudes./// Más detalles en el artículo <doc:NetworkGuide>.

Funcionalidades de Markdown: DocC admite encabezados, listas, tablas, imágenes e incluso diagramas con Mermaid:

/// # Algoritmo de funcionamiento/// 1. Verificar caché/// 2. Si no hay, solicitud al servidor/// 3. Guardar el resultado

Creando documentación para un módulo completo

Añade un archivo Documentation.docc en la raíz del proyecto. Dentro, una estructura en Markdown:

// MyFramework.docc/MyFramework.md# ``MyFramework``

Biblioteca asíncrona para trabajar con la red.

## Topics

### Componentes principales- ``NetworkManager``- ``RequestBuilder``

### Extensiones- <doc:CustomizingRequests>