Diseñar para el consumidor: defectos y tipos que blindan

Una API es un reparto de trabajo. Todo lo que su autor no resuelva quedará resuelto —o no— por cada uno de sus consumidores, multiplicado por el número de llamadas que existan en el mundo. Bajo esa luz, dos decisiones que suelen presentarse como cuestiones de comodidad se revelan como decisiones económicas de primer orden: si ofreces valores por defecto o una familia de sobrecargas, y si tu tipo permite representar estados que tu implementación considera imposibles. La primera decide cuánta documentación tendrá que leer el consumidor; la segunda decide cuántas comprobaciones tendrá que escribir, y cuántas olvidará.

Un defecto vale por una familia entera

Muchas bibliotecas heredadas de otras tradiciones exponen la misma operación cuatro o cinco veces, cada una con un subconjunto de parámetros. En Swift eso casi nunca está justificado, porque los valores por defecto cubren el mismo espacio con una sola declaración.

// La familia heredada: cuatro simbolos, cuatro paginas de documentacion
func buscar(_ t: String)
func buscar(_ t: String, sensible: Bool)
func buscar(_ t: String, sensible: Bool, limite: Int)
func buscar(_ t: String, sensible: Bool, limite: Int, orden: Orden)

// La forma idiomatica: un simbolo, una pagina
func buscar(_ texto: String,
            sensibleAMayusculas: Bool = false,
            limite: Int = .max,
            orden: Orden = .relevancia) -> [Resultado]

La ventaja obvia es de mantenimiento: añadir un parámetro nuevo con defecto no rompe a nadie, mientras que añadirlo a una familia obliga a duplicar la mitad de las combinaciones. Pero la ventaja decisiva es cognitiva y ocurre en el punto de uso. Con sobrecargas, el consumidor debe elegir primero qué símbolo llamar, decisión que exige comparar firmas; con defectos, llama siempre al mismo y solo decide qué desviaciones del comportamiento normal necesita. El autocompletado deja de ser un menú de opciones equivalentes y pasa a ser una lista de ajustes.

Los defectos comunican además una información que ninguna sobrecarga transmite: cuál es el comportamiento canónico. Cuando lees que el orden por defecto es la relevancia y el límite es ilimitado, has aprendido de un vistazo qué esperaba el autor que hicieras la mayoría de las veces. Esa señal desaparece por completo en una familia donde todas las variantes tienen el mismo rango.

Estados inválidos que no se pueden escribir

La segunda técnica es más profunda y cambia la naturaleza de lo que estás publicando. En vez de documentar qué combinaciones de valores son legales y comprobarlas en tiempo de ejecución, se elige una representación en la que las ilegales no existen como valores posibles.

// Prohibido pero expresable: hay que documentarlo y validarlo
struct Peticion {
    var exito: Bool
    var datos: Data?      // valido solo si exito es cierto
    var error: Error?     // valido solo si exito es falso
}

// Inexpresable: el compilador cierra la puerta
enum Peticion {
    case exito(Data)
    case fallo(Error)
}

El primer tipo admite cuatro combinaciones, de las cuales dos son estados corruptos que la implementación jamás debe producir y que, sin embargo, cualquier consumidor puede construir. El segundo admite exactamente dos, y las dos son válidas. La diferencia no es de estilo: es la diferencia entre una invariante que se mantiene por vigilancia y una que se mantiene por construcción.

flowchart LR
A[Invariante del dominio] --> B{Se puede codificar en el tipo}
B -- Si --> C[Enum o inicializador que valida]
B -- No --> D{Se detecta pronto}
D -- Si --> E[Precondicion documentada]
D -- No --> F[Riesgo latente y pruebas]
C --> G[Error en compilacion]
E --> H[Error al ejecutar]
style C fill:#a6e3a1,color:#11111b
style G fill:#a6e3a1,color:#11111b
style F fill:#f38ba8,color:#11111b

El repertorio de Swift para esto es amplio y conviene tenerlo presente como catálogo. Las enumeraciones con valores asociados eliminan las combinaciones imposibles de campos. Los inicializadores que fallan o lanzan concentran la validación en un único punto y garantizan que todo valor existente ya pasó por él. Los genéricos con restricciones impiden aplicar una operación a un tipo que no la soporta. Y los tipos opacos permiten devolver algo utilizable sin exponer la representación que el consumidor podría manipular mal.

struct Porcentaje {
    let valor: Double
    init?(_ crudo: Double) {
        guard (0...100).contains(crudo) else { return nil }
        valor = crudo
    }
}

Nótese lo que ese inicializador consigue: a partir de ahí, ninguna función que reciba un Porcentaje necesita comprobar el rango, y ninguna revisión de código necesita verificar que lo hizo. La validación se ha pagado una vez, en la frontera, en lugar de en cada uso.

Envolver primitivos cuesta poco y ahorra mucho

El caso particular más rentable de la técnica anterior es el de los identificadores y las magnitudes representados como cadenas o números desnudos. Dos parámetros del mismo tipo primitivo son intercambiables para el compilador, y por tanto un error de orden pasa silenciosamente.

// El compilador acepta encantado los argumentos invertidos
func transferir(de origen: String, a destino: String, importe: Double)

// Ahora el intercambio no compila
struct CuentaID: Hashable { let valor: String }
struct Euros { let centimos: Int }

func transferir(de origen: CuentaID, a destino: CuentaID, importe: Euros)

El coste de esos envoltorios es prácticamente nulo en ejecución: un struct con un único campo almacenado se representa igual que el campo que contiene, de modo que no hay indirección ni asignación de memoria adicional. El coste real es de escritura, y se reduce mucho conformando a ExpressibleByStringLiteral o a los protocolos numéricos cuando la ergonomía lo pida.

Las unidades merecen mención aparte porque son la fuente clásica de fallos caros. Un Double llamado duracion no dice si son segundos o milisegundos, y la biblioteca estándar resolvió ese problema para sí misma introduciendo Duration en vez de seguir aceptando números sueltos. La lección se traslada directamente: si tu dominio tiene magnitudes, la unidad pertenece al tipo y no al nombre del parámetro ni al comentario.

El precio de blindar

Sería deshonesto presentar estas técnicas sin su factura. Blindar una API tiene tres costes concretos y hay contextos donde no compensan.

El primero es la rigidez ante la evolución. Una enumeración pública con casos exhaustivos es un contrato fuerte, y añadirle un caso rompe a todo consumidor que la conmute sin caso por defecto. Por eso las bibliotecas que atraviesan módulos disponen de la anotación de no congelación, y por eso conviene pensar dos veces antes de exponer un enum público en un dominio que aún se mueve.

El segundo es la fricción de conversión. Cada envoltorio obliga a construir y desenvolver en las fronteras, y cuando una API está mal cosida con las adyacentes el consumidor pasa la mitad del código traduciendo. La señal de alarma es ver conversiones repetidas en el lugar de la llamada.

El tercero es la complejidad de lectura. Un tipo que codifica seis invariantes mediante genéricos anidados puede ser irreprochable y a la vez ilegible, y un mensaje de error del compilador sobre tipos genéricos profundos cuesta más tiempo que la comprobación en ejecución que ha sustituido. El criterio práctico es proporcional: cuanto más grave sea la consecuencia del mal uso y más lejos esté de detectarse, más justificado está el blindaje.