Fundamentos del diseño de bibliotecas de software

⏱ Dedicación recomendada: 0 minutos
Esto considera el contenido visible y relevante, e ignora texto colapsado o marcado como opcional.

---

El desarrollo de bibliotecas de software es fundamental para crear herramientas reutilizables que ayudan a otras aplicaciones y desarrolladorxs a resolver problemas comunes de forma eficiente. En lugar de reescribir lógica repetitiva en cada proyecto, las bibliotecas ofrecen funcionalidades encapsuladas y optimizadas, listas para integrarse en distintos entornos de desarrollo.

Desde cálculos científicos hasta manipulación de datos, las bibliotecas están en el corazón del software moderno. Algunos ejemplos ampliamente utilizados incluyen:

• 🧮 NumPy (Python): estructuras y operaciones optimizadas para cálculos numéricos de alto rendimiento.
• 📦 Lodash (JavaScript): utilidades para manipular arreglos, objetos y funciones.
• ⚡ Arrow (Kotlin): soporte para programación funcional y gestión segura de errores con estructuras como Either y Validated.
• 🔗 Boost (C++): extensiones al lenguaje con estructuras avanzadas y herramientas de concurrencia.

Cada una de estas bibliotecas muestra cómo un buen diseño de API, combinado con una implementación eficiente, puede reducir la complejidad, mejorar la productividad y fomentar la reutilización.

En esta lección, exploraremos los principios esenciales del diseño de bibliotecas de software, junto con buenas prácticas para construir APIs efectivas, claras y fáciles de adoptar. Veremos cómo se aplican estos conceptos en bibliotecas reales, desde JavaScript hasta Kotlin.

🔗 APIs: La Base del Desarrollo de Software Moderno

Una API (Application Programming Interface) es un conjunto de reglas y herramientas que define cómo interactuar con una biblioteca o sistema. Actúa como un bloque de construcción reutilizable, permitiendo que aplicaciones y desarrolladorxs agreguen funcionalidades de manera eficiente y estandarizada.

Las APIs son esenciales en el desarrollo moderno de software y suelen proporcionarse mediante bibliotecas, como NumPy para cálculos numéricos en Python o Lodash para manipulación de datos en JavaScript.

✅ Características de una Buena API

🎯 1. Modelar el Problema Correctamente

Una API bien diseñada debe proporcionar una abstracción clara y efectiva del problema que resuelve.

✔️ Propósito claro → Cada función, clase y variable debe estar bien definida.
✔️ Consistencia → Los nombres y estructuras deben ser uniformes para facilitar su uso.

🔹 Ejemplo real: kotlinx-datetime (Kotlin)

val now: Instant = Clock.System.now()
val localDateTime = now.toLocalDateTime(TimeZone.UTC)

¿Qué acabamos de hacer?

• Clock.System.now() modela de forma explícita el concepto de "tiempo actual" desde un reloj del sistema.
• toLocalDateTime deja claro que estamos convirtiendo un Instant a una fecha local, y exige que se indique la TimeZone, lo que evita ambigüedad.
• La API evita nombres genéricos como convert o getTime, y utiliza nombres que describen con precisión la transformación o propósito.

Resultado

Esta API modela el dominio del tiempo y las zonas horarias de forma clara y predecible, lo que facilita su uso correcto y evita errores comunes como la omisión de zonas horarias.

🔒 2. Ocultar Detalles de Implementación

Una API debe esconder los detalles internos, permitiendo modificaciones sin afectar a quienes la utilizan.

✔️ Encapsulación → Expone solo lo necesario mediante métodos públicos.
✔️ Interfaz clara → Permite interactuar con la API sin conocer su implementación interna.
✔️ Separación de preocupaciones → Divide la API en módulos bien definidos.

🔹 Ejemplo real: Ktor (Kotlin)

val client = HttpClient()
val response: HttpResponse = client.get("https://lufia-api.example.com/ancient-cave/floor/20")

println(response.status)
println(response.bodyAsText())

¿Qué acabamos de hacer?

Este ejemplo demuestra cómo Ktor aplica el principio de ocultar detalles de implementación:

• Encapsulación: Clases como HttpClient, HttpResponse o HttpRequestBuilder exponen una interfaz limpia. Internamente, Ktor utiliza múltiples módulos y clases con internal o private para proteger su lógica de serialización, construcción de solicitudes, manejo de errores, etc.
• Interfaz clara: El usuario interactúa con funciones como get() o bodyAsText() sin necesidad de conocer cómo se gestiona la conexión, el parseo del cuerpo o los encabezados HTTP.
• Separación de preocupaciones: Ktor divide su funcionalidad en módulos (client-core, client-json, client-logging, etc.). Cada uno cumple una función específica y puede ser intercambiado o desactivado sin modificar el resto de la API pública.

Resultado

Ktor permite construir clientes HTTP modulares con una interfaz sencilla, mientras oculta detalles como la serialización, el manejo de errores o la infraestructura de conexión. Puedes pedir los datos del Ancient Cave sin saber si fueron obtenidos por sockets, corutinas o magia de Artea.

⚖️ 3. Diseño Basado en la Simplicidad

"Cada elemento público en tu API es una promesa: una promesa de que soportarás esa funcionalidad por toda la vida de la API."
— Reddy, 2011

Una API debe ser lo más pequeña posible para facilitar su mantenimiento y comprensión.

✔️ Simplicidad → Reduce el número de elementos públicos.
✔️ Evita duplicación (DRY) → No repitas funcionalidades.
✔️ Principio de responsabilidad única → Cada componente debe tener una única responsabilidad.

🔹 Ejemplo real: Lodash (JavaScript)

import _ from 'lodash';

const characters = [
  { name: "Celty", alias: "The Headless Rider" },
  { name: "Shizuo", alias: "The Strongest Man in Ikebukuro" },
  { name: "Izaya", alias: "Information Broker" }
];

const names = _.map(characters, "name");

console.log(names); // ["Celty", "Shizuo", "Izaya"]

¿Qué acabamos de hacer?

Este ejemplo refleja cómo Lodash promueve un diseño basado en la simplicidad:

• Simplicidad: _.map() permite extraer un campo con solo pasar el nombre de la propiedad, sin necesidad de definir una función personalizada para cada caso.
• No duplicación (DRY): Evita que cada extracción de nombres se haga con lógica repetida como characters.map(c => c.name), promoviendo reutilización.
• Responsabilidad única: _.map() solo transforma cada elemento de la colección, delegando cualquier otra transformación o filtrado a funciones distintas como _.filter, _.pick o _.sortBy.

Resultado

Lodash mantiene una API minimalista, coherente y reutilizable. Sus funciones hacen exactamente una cosa y la hacen bien — siguiendo el espíritu de menos es más.

🛠️ 4. Fácil de Usar y Difícil de Usar Incorrectamente

✔️ Intuitiva → El uso de la API debe ser evidente con solo ver los nombres de los métodos.
✔️ Difícil de usar mal → Diseñada para prevenir errores comunes.
✔️ Evita abreviaciones y siglas confusas → Usa nombres descriptivos y estándar.

🔹 Ejemplo real: Datetime (Python)

from datetime import datetime, timedelta

now = datetime.now()
tomorrow = now + timedelta(days=1)

print(f"Hoy es {now.date()} y mañana será {tomorrow.date()}")

¿Qué acabamos de hacer?

La biblioteca estándar datetime de Python es un gran ejemplo de API bien diseñada:

• ✅ Intuitiva: Los nombres como datetime.now(), timedelta, y date() son autodescriptivos.
• 🔒 Difícil de usar mal: No puedes sumar dos fechas arbitrariamente. Solo puedes operar con tipos compatibles (datetime + timedelta), lo cual previene errores lógicos comunes.
• 📚 Consistencia semántica: Todos los nombres están bien definidos y siguen una lógica uniforme; no hay siglas innecesarias ni convenciones poco claras.

Resultado

El diseño de datetime hace que trabajar con fechas y tiempos en Python sea directo y seguro. Gracias a su claridad y restricciones de tipos, es difícil cometer errores comunes como sumar dos fechas directamente o usar unidades inconsistentes.

🔗 5. Cohesión Alta y Bajo Acoplamiento

✔️ Alta cohesión → Un módulo debe centrarse en una sola tarea.
✔️ Bajo acoplamiento → Los componentes deben poder cambiar sin afectar a otros.

🔹 Ejemplo real: serde, la biblioteca de serialización en Rust

use serde::{Serialize, Deserialize};
use serde_json;

#[derive(Serialize, Deserialize, Debug)]
struct Character {
    name: String,
    level: u32,
}

fn main() {
    let json = r#"{"name":"Maxim","level":99}"#;
    let c: Character = serde_json::from_str(json).unwrap();
    println!("{:?}", c);
}

¿Qué acabamos de hacer?

La arquitectura de serde ejemplifica bien los principios de diseño:

• ✅ Alta cohesión:
  El núcleo (serde) se enfoca exclusivamente en definir las abstracciones de serialización/deserialización. Otros crates (como serde_json, serde_yaml, serde_cbor) implementan esos conceptos para distintos formatos, sin mezclar responsabilidades.
• 🔌 Bajo acoplamiento:
  Puedes cambiar de serde_json a serde_yaml sin modificar tu modelo de datos. Incluso puedes definir tus propios serializadores si necesitas un formato personalizado. La lógica de negocio y los datos están desacoplados de la lógica de formato.

Resultado

El diseño modular de serde permite que sea adoptada ampliamente sin arrastrar dependencias innecesarias. Esta separación clara de responsabilidades ha convertido a serde en una de las bibliotecas más usadas y respetadas del ecosistema Rust.

🔍 6. Estabilidad, Documentación y Pruebas

✔️ Estabilidad → Usa versionado y evita cambios incompatibles.
✔️ Documentación → Explica la API con ejemplos claros.
✔️ Pruebas → La API debe contar con tests automatizados.

🔹 Ejemplo (Kotlin - Deprecación de Métodos Viejos):

@Deprecated("Use sendSecureEmail instead", ReplaceWith("sendSecureEmail(to, subject, body)"))
fun sendEmail(to: String, subject: String, body: String) { /* ... */ }

📌 Buena práctica: Indica claramente qué método reemplaza al obsoleto.

🔹 Ejemplo (Kotlin - Prueba Unitaria con Kotest):

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.shouldBe

class AuthServiceTest : StringSpec({
    "should return true when credentials are valid" {
        val auth = AuthService()
        auth.login("user", "password") shouldBe true
    }
})

📌 Buena práctica: Las pruebas aseguran la estabilidad de la API a largo plazo.

---

Una API bien diseñada no solo facilita su uso, sino que también mejora la modularidad, mantenibilidad y seguridad del software. Al aplicar estos principios:

✅ Modela el problema de forma clara.
✅ Oculta detalles innecesarios y favorece la encapsulación.
✅ Prioriza la simplicidad y evita agregar funciones innecesarias.
✅ Es intuitiva y difícil de usar mal.
✅ Promueve cohesión alta y bajo acoplamiento.
✅ Garantiza estabilidad con documentación y pruebas.

Si sigues estas prácticas, tu API será más eficiente, fácil de mantener y adoptada con mayor rapidez por otrxs desarrolladorxs. 🚀

📚 ¿Qué es una biblioteca de software?

Una biblioteca es un conjunto de funciones, clases y herramientas reutilizables que facilitan tareas comunes en el desarrollo de software. Permiten a quienes desarrollan escribir menos código, mejorar la modularidad y evitar la repetición de lógica.

Ejemplos:

• NumPy (Python) → Computación científica.
• Lodash (JavaScript) → Manipulación de arrays y objetos.
• Guava (Java) → Colecciones avanzadas y utilidades.

🔍 Diferencias entre una biblioteca y una aplicación

📌 Característica	📚 Bibliotecas	🖥️ Aplicaciones
Finalidad	Proveer funcionalidades reutilizables	Resolver un problema específico
Ejecutables	❌ No pueden ejecutarse por sí solas	✅ Pueden ejecutarse de forma independiente
Interacción	API para desarrolladorxs	Interfaz para usuarixs (UI/CLI)
Ejemplos	NumPy, Guava, Boost	Chrome, Photoshop, IntelliJ

🏗️ Principios de Diseño de Bibliotecas

Para que una biblioteca sea efectiva, debe cumplir con ciertos principios de diseño.

🏛️ 1. Interfaces Simples y Coherentes

✔️ API fácil de usar → Debe ser intuitiva sin necesidad de leer documentación extensa.
✔️ Consistencia → Uso uniforme de nombres y estructuras.

// ❌ Inconsistente (nombres y orden de parámetros diferentes)
parseJSON(validate = true, "data.json")
readXml("data.xml", validate = true)

// ✅ Consistente (sigue un mismo patrón)
Parser.json("data.json", validate = true)
Parser.xml("data.xml", validate = true)

🔒 2. Encapsulación y Ocultamiento de Implementación

✔️ Solo exponer lo necesario → Los detalles internos deben estar ocultos.
✔️ Modularidad → Cada parte de la biblioteca debe ser independiente.

class Database private constructor() {
    private val connection = connectToDatabase() // 🔒 Oculto

    fun query(sql: String): ResultSet = connection.executeQuery(sql)

    companion object {
        fun create(): Database = Database()
    }
}

📌 El usuario solo interactúa con query() sin preocuparse por la conexión interna.

⚖️ 3. Cohesión y Bajo Acoplamiento

✔️ Alta cohesión → Cada módulo debe hacer una sola cosa bien.
✔️ Bajo acoplamiento → Los cambios en una parte no deben afectar otras.

// ❌ Mal diseño: la clase maneja tanto autenticación como validación de datos.
class AuthService {
    fun login(user: String, pass: String) { /*...*/ }
    fun isValidEmail(email: String): Boolean { /*...*/ }
}

// ✅ Buen diseño: separación de responsabilidades.
class AuthService { fun login(user: String, pass: String) { /*...*/ } }
class Validator { fun isValidEmail(email: String): Boolean { /*...*/ } }

🔥 Ejemplos de Bibliotecas Populares

1️⃣ Lodash (JavaScript) – Utilidades para Arrays y Objetos

📌 Facilita la manipulación de datos en JavaScript.

import _ from 'lodash';
const numbers = [1, 2, 3, 4, 5];
console.log(_.chunk(numbers, 2)); // [[1, 2], [3, 4], [5]]

2️⃣ NumPy (Python) – Computación Numérica

📌 Optimiza operaciones matemáticas con arrays y matrices.

import numpy as np
a = np.array([1, 2, 3])
b = np.array([4, 5, 6])
print(np.dot(a, b))  # Output: 32

3️⃣ Guava (Java) – Colecciones y Utilidades

📌 Extiende las capacidades estándar de Java con estructuras de datos avanzadas.

Multimap<String, String> multimap = ArrayListMultimap.create();
multimap.put("fruit", "apple");
multimap.put("fruit", "banana");
System.out.println(multimap); // {fruit=[apple, banana]}

4️⃣ Boost (C++) – Extensiones para C++

📌 Proporciona herramientas avanzadas para manipulación de datos.

#include <boost/algorithm/string.hpp>
std::string str = "Hello Boost";
boost::to_upper(str);
std::cout << str;  // Output: HELLO BOOST

5️⃣ Arrow (Kotlin) – Programación Funcional

📌 Simplifica el manejo de errores y estructuras de datos inmutables.

import arrow.core.*

fun divide(a: Int, b: Int): Either<String, Int> =
    if (b == 0) "Cannot divide by zero".left() else (a / b).right()

println(divide(4, 2))  // Output: Right(2)

🎯 Conclusiones

Diseñar bibliotecas de software va mucho más allá de simplemente escribir funciones reutilizables: implica construir herramientas que otras personas usarán y en las que confiarán. Una buena biblioteca ofrece una API clara, coherente y segura que reduce la complejidad del desarrollo, promueve la reutilización y facilita el mantenimiento del código.

Hemos visto cómo una buena API:

• abstrae correctamente el problema que resuelve,
• oculta detalles innecesarios,
• mantiene su interfaz simple y coherente,
• está diseñada para evitar mal uso,
• está bien estructurada internamente (alta cohesión, bajo acoplamiento),
• y cuenta con estabilidad, documentación y pruebas adecuadas.

🔑 Puntos clave

• Una biblioteca es tanto una herramienta técnica como una interfaz para otras personas. Su diseño debe enfocarse en la experiencia de quien la usa.
• Las decisiones de diseño impactan directamente en la seguridad, mantenibilidad y adopción de la biblioteca.
• Aplicar principios como encapsulación, simplicidad, cohesión y versionado cuidadoso mejora significativamente la calidad del software.

🧰 ¿Qué nos llevamos?

Diseñar bibliotecas no es solo un ejercicio técnico: es una forma de comunicación. Cada función pública, cada nombre de parámetro, cada estructura expuesta es una invitación a que otra persona confíe en tu código. Al aplicar principios como claridad, simplicidad, encapsulación y pruebas, no solo estás resolviendo un problema, estás construyendo herramientas que perdurarán y crecerán junto con quienes las usan.

Lo más valioso que puedes llevarte de esta unidad es que una buena biblioteca no se mide solo por lo que hace, sino por cómo hace sentir a quien la utiliza: segura, guiada y capaz.

Crear bibliotecas es crear comunidad. Y eso, en sí mismo, es un acto de generosidad.

📖 Referencias

🔥 Recomendadas

• 📚 Introduction. (2024). En M. Reddy, API design for C++ (Second edition, pp. 1–24). Morgan Kaufmann.
• 📚 Qualities. (2024). En M. Reddy, API design for C++ (Second edition, pp. 25–80). Morgan Kaufmann.