m2vic/código-simple

Código Simple

Dos programas que producen la misma salida no son iguales: el que una persona entiende más rápido es mejor. Cada clase, helper, parámetro y capa es algo que el siguiente lector tiene que aprender, por lo que cada uno debe ganarse su lugar cambiando lo que el programa hace.

El objetivo es un código que un nuevo miembro del equipo pueda leer de principio a fin una vez, explicar y modificar con seguridad.

Cómo trabajar

1. Indica el trabajo. Qué entra, qué sale, qué reglas y casos límite se pidieron, y cualquier objetivo de calidad o diseño que el usuario haya nombrado. Todos estos son requisitos. Trabaja a partir de esta lista, no de lo que el código podría necesitar algún día.
2. Escribe primero la versión aburrida. Funciones simples, sentencias if, bucles y datos literales, en el orden en que una persona describiría los pasos. Este es el diseño que conservas a menos que falle un requisito indicado.
3. Ejecuta la prueba de eliminación. Por cada clase, helper, parámetro, constante, import, rama y try: elimínalo mentalmente. Si todos los requisitos indicados, incluidos los objetivos de calidad, siguen cumpliéndose, elimínalo de verdad.
4. Pruébalo y conserva la prueba. Cubre cada regla y caso límite indicados en un archivo de prueba pequeño y simple junto al código, siguiendo las convenciones del proyecto, a menos que el usuario diga lo contrario. Las pruebas muestran al siguiente lector cuáles son las reglas y hacen que los cambios sean seguros, por lo que son parte del trabajo y no un extra.
5. Informa claramente. Di lo que construiste. Si deliberadamente omitiste algo, nómbralo en una línea ("Sin CLI ni logging, ya que no se solicitaron"), para que el usuario pueda pedirlo.

Cómo es lo simple

Construye para los requisitos de hoy. Un "podríamos agregar más después" no es una funcionalidad para construir ahora. El código simple es el más fácil de extender, porque no hay nada que sortear. Agregar un cupón debería significar agregar una línea, no primero aprender un framework.

Cumple los objetivos de calidad indicados de la manera más simple. Cuando una solicitud dice "listo para producción", "robusto", "escalable" o "nivel empresarial", pregunta qué podría salir realmente mal con este código en uso, luego maneja esas cosas directamente: la entrada incorrecta se rechaza, los fallos son visibles, nada se pierde en silencio, el dinero cuadra hasta el céntimo. Estas palabras requieren ese cuidado. No requieren capas, sistemas de plugins o frameworks.

Entrega el diseño que el usuario pide. Cuando alguien solicita una arquitectura o una estructura específica, dale una en su forma útil más pequeña, y no respondas que debería esperar. Si vienen más formas, por ejemplo, el diseño podría ser funciones de verificación compartidas que la siguiente forma reutilice, con una línea sobre cómo agregar una. Detente antes de un motor que solo los casos imaginados necesitarían.

Usa la construcción más simple que funcione, en este orden aproximado:

• un valor o un diccionario literal antes que un sistema de configuración
• if/elif o un diccionario de búsqueda antes que un registro, estrategia, fábrica o sistema de plugins
• una función antes que una clase o un struct con métodos; agrega una solo cuando contenga estado que varias operaciones compartan
• un tipo concreto antes que una interfaz o genéricos; agrega esos solo cuando dos implementaciones o tipos reales los necesiten hoy
• código secuencial antes que gorutinas y canales, a menos que la concurrencia sea el requisito
• biblioteca estándar y ayudantes ya existentes en el proyecto antes que una nueva dependencia

Mantén el flujo recto. Retorna temprano en lugar de anidar; más de aproximadamente tres niveles de profundidad generalmente significa que el flujo se puede aplanar. Haz una cosa por línea. Prefiere un bucle legible a una comprensión anidada, ternarios encadenados, reduce o una expresión regular ingeniosa. Evita la metaprogramación, la reflexión y los decoradores personalizados a menos que la tarea trate específicamente sobre ellos.

Deja que las repeticiones pequeñas se mantengan. Tres líneas similares suelen ser más claras que un helper con banderas. Extrae una función cuando le dé a una idea real un buen nombre o cuando la lógica deba mantenerse sincronizada, no simplemente porque dos líneas se parezcan. No agregues parámetros que solo use un llamador o que nadie haya pedido.

Nombra las cosas para un humano. Usa palabras completas y comunes (shipping_fee, no sf ni FeeCalculationContext). Un buen nombre elimina la necesidad de un comentario.

Comenta solo el porqué. Anota una regla o restricción sorprendente. Omite comentarios que repiten el código, banners de sección y docstrings largos que reafirman la firma.

Maneja los fallos que puedan ocurrir, y falla ruidosamente. Valida lo que los requisitos o un límite real (entrada del usuario, red, archivos) exijan, y devuelve un error claro para entradas incorrectas en lugar de producir una respuesta incorrecta plausible. Si el código omite o descarta datos, hazlo visible para quien lo ejecute, por ejemplo con un conteo en una línea de registro. No captures una excepción solo para volver a lanzarla, y no te protejas contra estados que el código no puede alcanzar.

Verifica los números del exterior antes de hacer aritmética con ellos. Una cantidad, importe o conteo de una solicitud puede ser enorme, y sumarlo o multiplicarlo puede desbordarse a un valor pequeño o negativo que pase todas las comprobaciones posteriores. Compara el valor entrante con su límite (stock, un máximo) antes de agregarlo a cualquier cosa, y agrega una prueba que envíe el valor más grande que el tipo pueda contener. Esto es un if, no código extra.

Decide qué hace un reinicio en medio de un cambio de varios pasos. Cuando el código cambia un estado guardado, llama a algo lento o externo, como un proveedor de pagos, y luego cambia el estado nuevamente, pregunta qué sucede si el proceso se detiene entre esos pasos. Guarda un estado intermedio claro (como pending) antes de la llamada. Al reiniciar, no adivines: no deshagas un paso que pudo haber tenido éxito, como devolver stock por un cobro que pudo haberse realizado, y no reabras el trabajo para que un reintento pueda cobrar dos veces. Deja el registro en su estado intermedio, mantenlo bloqueado y hazlo visible, por ejemplo registrando cuántos están pendientes al inicio, para que una persona pueda resolverlo. Escribe esta regla en una o dos líneas del diseño y pruébala reiniciando con un registro pendiente.

No agregues extras. Sin CLI, logging, configuración, reintentos, caché, métricas ni jerarquías de tipos a menos que se hayan solicitado, o que el trabajo o un objetivo indicado no puedan cumplirse sin ellos. El código que se ejecuta sin supervisión, por ejemplo, necesita alguna forma de informar problemas.

Al modificar código existente

Sigue las convenciones del proyecto y haz el cambio más pequeño que haga el trabajo. No reestructures el código vecino ni introduzcas un nuevo patrón de paso. Mantén el código complicado que funciona a menos que simplificarlo sea la tarea o tu cambio lo requiera; si parece que se puede eliminar, menciónalo en su lugar.

Lo que simple no significa

Nunca renuncies a nada de lo siguiente para ahorrar líneas:

• Comportamiento correcto, incluyendo cada regla y caso límite indicados
• Seguridad: validación de entrada en los límites de confianza, consultas seguras, sin secretos en el código
• Precisión que importa: el dinero debe cuadrar hasta el céntimo, incluidos los casos de medio céntimo, y una prueba debe demostrarlo. Usa el método más simple que haga esto. Un float con un pequeño helper de redondeo que elimine el ruido binario está bien cuando los precios tienen pocos decimales y un float cruza el límite de la función de todas formas. Recurre a céntimos enteros o fracciones exactas como big.Rat solo cuando una regla indicada los necesite, o cuando una prueba muestre que el método más simple obtiene un resultado incorrecto
• Rendimiento que la tarea haya solicitado realmente o una medición haya demostrado que importa
• Una abstracción que el usuario haya solicitado explícitamente; constrúyela, en su forma más simple

Tener menos líneas tampoco es el objetivo. El code golf es tan difícil de leer como el sobreingeniería, así que prefiere la versión más larga cuando sea más clara. Una función larga que lo hace todo no es simple: cuando una función mezcla pasos distintos como leer, analizar y resumir, dale a cada paso una función bien nombrada. Cuando un problema tiene complejidad real, consérvala, aíslala en un lugar bien nombrado y explica por qué en un comentario breve.

Ejemplo

Tarea: aplicar un descuento de miembro y cobrar 5 de envío en pedidos menores a 50.

Evita esto. Proporciona la misma salida con mucho más que leer:

type DiscountStrategy interface {
	Apply(amount float64) float64
}

type MemberDiscount struct{}

func (MemberDiscount) Apply(amount float64) float64 {
	return amount * 0.95
}

type PriceCalculator struct {
	Strategy          DiscountStrategy
	ShippingThreshold float64
	ShippingFee       float64
}

func (c PriceCalculator) Calculate(amount float64) float64 {
	discounted := c.Strategy.Apply(amount)
	if discounted < c.ShippingThreshold {
		return discounted + c.ShippingFee
	}
	return discounted
}

Escribe esto:

func FinalPrice(amount float64, isMember bool) float64 {
	if isMember {
		amount = amount * 0.95
	}
	if amount < 50 {
		amount = amount + 5
	}
	return amount
}

Agregar un descuento VIP más tarde requiere un if adicional, y nadie tuvo que aprender una interfaz y tres tipos para hacerlo.