Cómo escribir funciones que se entienden sin comentarios

Escribir funciones que no necesitan comentarios explicativos es la marca de un desarrollador que valora el código limpio y la legibilidad. Los comentarios son una señal de alarma: a menudo intentan compensar un código confuso o un mal naming. Mi regla es que el código debe ser su propia documentación.

Cuando el código se entiende por sí mismo, no tienes que mantener dos fuentes de verdad — el código y el comentario. Esto reduce errores y facilita el mantenimiento a largo plazo.

Los comentarios no corrigen un código deficiente

Un comentario que explica qué hace una función es redundante si la función está bien escrita. Si necesitas un comentario para entender el propósito de calcularImpuestos(precio, porcentaje), la función ya tiene un problema de naming o de diseño. Los comentarios envejecen y se desincronizan con el código.

Lo que sí es útil, en ocasiones, es un comentario que explique por qué se hizo una decisión concreta, especialmente si fue una solución de compromiso o una restricción de negocio. Pero estos son la excepción, no la norma. Un comentario que dice // Esta función suma dos números es simplemente ruido.

// Mal ejemplo: el comentario no aporta nada
function sumarNumeros(a, b) {
  // Suma dos números y devuelve el resultado
  return a + b;
}

// Buen ejemplo: la función es clara por sí misma
function calcularTotalCompra(precioUnitario, cantidad) {
  return precioUnitario * cantidad;
}

Nombrar bien es documentar sin escribir más

El naming es la herramienta más potente para la legibilidad del código. Un buen nombre de función describe su intención y sus efectos secundarios. Un buen nombre de variable describe el tipo de dato que contiene y su propósito.

Evita abreviaturas crípticas o nombres genéricos como data, item, handler. Sé explícito. Si una función se llama procesar, el lector no sabe qué procesa ni cómo. Si se llama generarInformeMensualVentas, su propósito es inequívoco. Tengo un artículo específico sobre nombrar cosas en el código con buenas prácticas que explora esto en profundidad.

// Mal naming
function proc(d, u) { /* ... */ }

// Buen naming
function procesarTransaccionesDiarias(datosTransaccion, usuarioActual) { /* ... */ }

Una función, una responsabilidad

Las funciones deben hacer una sola cosa y hacerla bien. Este es el principio de Responsabilidad Única (SRP). Cuando una función tiene múltiples responsabilidades, su nombre se vuelve genérico, sus parámetros aumentan, y se vuelve difícil de leer y mantener.

Si una función guardarUsuario también envía un email de bienvenida, valida datos y actualiza un log, está haciendo demasiado. Cada una de esas acciones debería ser una función separada. Esto mejora la legibilidad, facilita los tests y permite reutilizar piezas de código. Esto se alinea con la idea de modularidad que también se aplica en arquitectura hexagonal, donde cada componente tiene un rol definido.

// Función con múltiples responsabilidades
function crearUsuarioCompleto(datos) {
  validarDatos(datos);
  const usuario = guardarUsuarioEnBaseDeDatos(datos);
  enviarEmailBienvenida(usuario);
  registrarActividad(usuario, 'creado');
  return usuario;
}

// Funciones con una única responsabilidad
function validarDatosUsuario(datos) { /* ... */ }
function guardarUsuarioEnBaseDeDatos(datos) { /* ... */ }
function enviarEmailBienvenida(usuario) { /* ... */ }
function registrarActividad(usuario, evento) { /* ... */ }

Tradeoffs: Beneficios y complejidades del código limpio

Aplicar principios de código limpio y legibilidad tiene sus pros y sus contras. Es una inversión, no un atajo.

Lo que ganas:

• Mantenibilidad superior: El código es más fácil de entender, depurar y modificar.
• Menos errores: La simplicidad reduce la probabilidad de introducir bugs.
• Colaboración fluida: Otros desarrolladores pueden sumergirse en tu código sin una guía constante.
• Menor deuda técnica: Evitas que el proyecto se convierta en un monolito incomprensible con el tiempo.

Lo que complicas:

• Tiempo inicial de desarrollo: Pensar en un buen naming y dividir la lógica lleva más tiempo que “simplemente escribirlo”.
• Refactoring constante: A medida que los requisitos cambian, tendrás que refactorizar sin romper el código existente para mantener la legibilidad.
• Requiere disciplina: Es fácil caer en malos hábitos bajo presión.

Escribir código que se explica solo no es una habilidad que se aprende de la noche a la mañana. Es una disciplina que se cultiva con cada línea de código.

Si quieres profundizar en cómo mantener la calidad del código en tu equipo, el valor real del code review es un buen punto de partida. Además, para asegurar la robustez de tu software, considera cómo el testing automatizado puede ahorrarte dinero a largo plazo. Estas prácticas son clave para un desarrollo sostenible.