Principios de Ingeniería
Construye la solución correcta más pequeña que siga siendo comprensible y segura de cambiar. Trata los principios como herramientas para razonar, no como leyes que estén por encima de los requisitos, las convenciones del repositorio o la evidencia.
Ciclo de trabajo
- Establece el contrato. Lee el código relevante, los llamadores, las pruebas y las instrucciones del repositorio. Identifica el comportamiento requerido, las entradas, las salidas, los invariantes, los modos de fallo y las restricciones de compatibilidad. Distingue los hechos observados de las suposiciones. Pregunta solo cuando un requisito no resuelto cambie materialmente la solución.
- Elige un diseño proporcionado. Reutiliza patrones locales y capacidades existentes. Prefiere una implementación directa; añade estructura cuando esta contenga complejidad real o proteja un límite real. Considera la seguridad, la integridad de los datos y los límites de recursos donde el cambio los afecte.
- Cambia un aspecto a la vez. Mantén el diff cohesivo. Preserva el trabajo no relacionado. Separa la refactorización que preserva el comportamiento de los cambios intencionales de comportamiento para que cada uno sea revisable. Corrige la causa, no solo el síntoma observado.
- Verifica el comportamiento prometido. Usa la prueba significativa más estrecha o el escenario ejecutable, incluyendo las rutas de fallo relevantes. Inspecciona lo que realmente se ejecutó; una selección de pruebas vacía no prueba nada. Las pruebas que pasan son evidencia para las aserciones y rutas que ejercitan, no una prueba de toda la corrección o compatibilidad.
- Finaliza el cambio. Actualiza los llamadores, contratos y documentación afectados. Elimina el código que este cambio ha vuelto obsoleto. Informa brevemente del resultado, la verificación y cualquier limitación restante; explica un principio solo cuando haya influido materialmente en una decisión.
Escala este ciclo según el riesgo: un cambio de nombre local necesita poca ceremonia; un cambio en una API compartida o en datos persistidos necesita evidencia de consumidores y migración. No fabriques documentos de diseño ni una cadena de especialistas para ediciones rutinarias.
Depuración y flujo de trabajo del repositorio
Trata un fallo reportado por el usuario como una reproducción; no le pidas que lo repita meramente para confirmarlo. Separa el comportamiento observado de las hipótesis, luego recopila evidencia que distinga las causas probables. Usa una reproducción enfocada, una inspección dirigida o un depurador en lugar de cambiar el código por adivinación. Corrige la causa, preserva los diagnósticos útiles sin exponer secretos, y nunca suprimas un error para hacer que la ruta parezca exitosa. Añade la cobertura de regresión faltante y verifica el comportamiento de recuperación relevante cuando un fallo pueda dejar un estado parcial.
Usa los puntos de entrada existentes de compilación, prueba, ejecución y generación del repositorio. Lee sus prerrequisitos documentados e invoca los mismos comandos que usan los humanos y CI; no añadas una segunda cadena de herramientas ni requieras Make donde el repositorio tenga otra interfaz adecuada. Un comando de prueba sin pruebas coincidentes no es evidencia.
Mantén la documentación útil para colaboradores: preserva el por qué, los invariantes y los flujos clave que el código por sí solo no explica; actualiza los documentos afectados, eligiendo referencia de usuario, tutorial o material de solución de problemas para la audiencia. Evita reescrituras amplias de documentación no relacionadas con el cambio.
Principios de diseño
La corrección comienza con los contratos
Define lo que debe permanecer cierto antes de elegir un patrón. Haz que los estados inválidos sean difíciles de representar usando tipos adecuados, constructores y transiciones de estado explícitas. Mantén clara la propiedad del estado mutable y los ciclos de vida de los recursos.
Valida la entrada no confiable en los límites. No elimines comprobaciones meramente porque parezcan defensivas: establece si la condición es imposible, ya está garantizada o sigue siendo un modo de fallo real. Preserva el contexto de error útil sin filtrar secretos. Nunca conviertas un fallo en un resultado exitoso inventado.
Simplicidad: KISS y YAGNI
KISS significa minimizar la complejidad que un mantenedor debe entender, no meramente el recuento de líneas. YAGNI significa implementar los requisitos actuales en lugar de características futuras especulativas. Ninguna de las dos excusa la falta de manejo de errores, almacenamiento inseguro o un atajo no mantenible.
Evita plugins, frameworks genéricos, capas de configuración o puntos de extensión sin una necesidad presente. Un diseño simple aún puede tener límites claros que hagan que un cambio posterior sea económico.
Complejidad en todo el sistema
Distingue la complejidad esencial (requerida por el problema), la complejidad opcional (una capacidad con un costo) y la complejidad accidental (dificultad evitable en la implementación del comportamiento especificado). Úsalas como categorías de razonamiento, no como una cuota de características. Aplícalas a través de la implementación, la interfaz, la integración y el esfuerzo y riesgo de error de los usuarios: reducir el costo en un lugar puede trasladarlo a otro. Elimina la complejidad accidental; mantén la capacidad opcional cuando su valor para el usuario justifique su costo total de vida. Bajo una fecha límite, compara el valor de entrega ahora con el esfuerzo, soporte y mantenimiento de extremo a extremo; menos líneas o características por sí solas no establecen un costo total más bajo. Para ejemplos, consulta Complejidad, Interfaces y Rendimiento.
Cohesión, acoplamiento y ocultación de información
Agrupa el código que cambia por la misma razón; separa las preocupaciones que cambian independientemente. Oculta las opciones de implementación volátiles detrás de una interfaz pequeña y coherente. Prefiere un módulo profundo que haga un trabajo útil sobre una cadena de envoltorios de paso.
Una interfaz puede ser algo de propósito general cuando eso permite que un mecanismo compartido sirva a llamadores identificables sin incrustar la política de un llamador. Mantenla no más general de lo que justifican los usos actuales: necesidades futuras adivinadas pueden sobrecargar a los llamadores actuales. Elige una interfaz especializada cuando su contrato sea genuinamente específico.
La responsabilidad única se refiere a una razón coherente para cambiar, no a un método por clase. El bajo acoplamiento significa que los consumidores necesitan poco conocimiento de los internos, no que cada llamada requiera una interfaz. Mantén las direcciones de dependencia explícitas y evita los ciclos cuando sea práctico.
Abstracción y DRY
DRY significa una representación autoritativa de un conocimiento, no eliminar cada secuencia de apariencia similar. Comparte la lógica cuando los llamadores expresan la misma regla y deberían evolucionar juntos. Mantén el código superficialmente similar separado cuando pertenezca a diferentes conceptos o ciclos de vida.
Cuando el conocimiento también aparece en archivos generados, identifica su fuente autoritativa y generador. Protege las ediciones no relacionadas antes de la regeneración; resuelve la propiedad superpuesta en lugar de sobrescribir el trabajo del usuario. Actualiza la fuente, ejecuta el generador existente e inspecciona el diff derivado. No edites manualmente la salida generada como la corrección duradera ni añadas maquinaria de generación para trabajo trivial.
Antes de extraer, identifica el contrato compartido, las razones esperadas para el cambio y la complejidad que la abstracción elimina. No uses un umbral numérico de repetición como prueba. Un poco de duplicación puede costar menos que el acoplamiento incorrecto.
SOLID como preguntas de diagnóstico
Usa estas preguntas donde el diseño se beneficie; no impongas una arquitectura orientada a objetos en código procedimental o funcional.
- Responsabilidad única: ¿mezcla esta unidad preocupaciones que cambian independientemente?
- Abierto/cerrado: ¿hay un eje de variación demostrado que valga la pena aislar, en lugar de un marco de extensión hipotético?
- Sustitución de Liskov: ¿puede una implementación reemplazar a otra sin sorprender a los llamadores a través de precondiciones más fuertes, garantías más débiles o fallos incompatibles?
- Segregación de interfaz: ¿dependen los consumidores solo de las capacidades que utilizan?
- Inversión de dependencias: ¿debería una política estable depender de un contrato estrecho en lugar de detalles de E/S volátiles? Una función o parámetro puede proporcionar esa separación; no se requiere una jerarquía de clases.
Prefiere la composición sobre la herencia cuando la herencia no modele una relación genuina de sustituibilidad. Usa mecanismos idiomáticos del lenguaje en lugar de nombres de patrones como objetivo.
Legibilidad y menor sorpresa
Elige nombres que expongan el significado del dominio, las unidades y la propiedad. Mantén el flujo de control y los efectos secundarios fáciles de seguir. Usa comentarios para la justificación, restricciones y garantías no obvias, no para narrar declaraciones obvias.
Sigue las convenciones del repositorio a menos que causen un problema concreto. El tamaño de la función, el número de parámetros y la profundidad de anidamiento son señales de advertencia, no límites numéricos universales. La indirección extra no es automáticamente código más limpio. Los comentarios pueden preservar la justificación, las restricciones y una abstracción que el código por sí solo no explica; juzga su valor en contexto en lugar de eliminarlos o dividir la lógica cohesiva para cumplir una regla de longitud o recuento de comentarios.
Dependencias y rendimiento
Reutiliza una biblioteca mantenida y adecuada para capacidades establecidas difíciles, especialmente criptografía y manejo de protocolos. Evalúa la idoneidad, seguridad, licencia, compatibilidad, costo operativo y peso de la dependencia. No añadas una dependencia para una operación trivial ya servida por el lenguaje o el repositorio.
Elige estructuras de datos y algoritmos sensatos para los tamaños de entrada esperados. Evita el trabajo redundante obvio y la asignación o copia derrochadora. Mide los cuellos de botella sospechados antes de la optimización compleja; compara cargas de trabajo representativas y protege la corrección. Nombra la carga de trabajo, la métrica, la línea base, el objetivo y el criterio de parada; usa medidas vinculadas a resultados reales del usuario o del sistema, no recuentos de actividad. Detente una vez que se cumpla el contrato o una ganancia adicional no valga la complejidad y el mantenimiento añadidos. Decide si el contrato valora la latencia, el rendimiento o el uso de recursos: el procesamiento por lotes puede mejorar el rendimiento mientras empeora el tiempo de respuesta. No intercambies un requisito de latencia o memoria declarado por simplicidad estilística. Para ejemplos, consulta Complejidad, Interfaces y Rendimiento.
Filosofía Unix en la práctica
Escribe componentes cohesivos que hagan bien un trabajo y se compongan a través de contratos explícitos. Esto no requiere un proceso por función, microservicios, almacenamiento solo de texto o ausencia de estado en todas partes. Las bibliotecas internas con APIs claras pueden ser igualmente componibles.
- Separa el mecanismo de la política. Mantén la computación reutilizable independiente de la presentación, el entorno y las elecciones de negocio cambiantes cuando esa separación reduzca el acoplamiento.
- Diseña para la composición. Evita el estado global oculto y las rutas codificadas innecesarias. Haz explícitas las dependencias y los efectos; permite que los llamadores elijan destinos cuando sea apropiado.
- Prefiere representaciones inspeccionables. Usa estructuras de datos simples y formatos documentados. El texto es valioso para herramientas interoperables; los formatos binarios son válidos cuando la fidelidad, el volumen o el rendimiento los requieran.
- Mantén el funcionamiento ordinario silencioso, los fallos visibles. El silencio significa que no hay charla irrelevante, no datos de resultado faltantes o diagnósticos suprimidos.
- Reutiliza herramientas. Prefiere las capacidades existentes confiables sobre reconstruirlas. Mantén la automatización no interactiva cuando esté destinada a scripts.
Elige el estilo de interfaz por sus consumidores humanos y máquina, no por tradición. Una API de función o biblioteca, una CLI estable o un filtro pueden ser adecuados para llamadores de máquina y trabajo repetible; las tareas humanas pueden necesitar descubribilidad, retroalimentación o interacción directa. Si ambos son consumidores reales, separa la lógica de dominio de los envoltorios opcionales para que compartan comportamiento sin hacer obligatorio un GUI. Sigue el estilo más simple que cumpla el contrato. Consulta Interfaces Unix y Complejidad, Interfaces y Rendimiento para compensaciones prácticas.
Para el diseño de CLI, tuberías y configuración, lee Interfaces Unix. Cuando la complejidad, el estilo de interfaz o las compensaciones de rendimiento moldeen materialmente la decisión, lee Complejidad, Interfaces y Rendimiento. Para principios y ejemplos en competencia, lee Compensaciones. Estas referencias son condicionales; ninguna es obligatoria para una edición local no relacionada.
Para ejemplos prácticos de depuración, comandos de proyecto, artefactos generados, documentación de mantenedores y evaluación de dependencias, lee Depuración y Mantenimiento.
Evolución segura y verificación
Una refactorización preserva el comportamiento observable, incluyendo salidas, errores, efectos secundarios y contratos en los que confían los consumidores. No corrijas en silencio peculiaridades durante una refactorización. Un cambio de contrato intencional actualiza explícitamente las pruebas y consumidores afectados; las pruebas de requisitos obsoletos no son restricciones permanentes.
Protege los límites públicos con pruebas centradas en el comportamiento. Reutiliza la cobertura adecuada; añade pruebas de regresión o caracterización cuando una ruta importante esté desprotegida. Prefiere implementaciones reales o simulaciones enfocadas cuando sea práctico, pero usa dobles para aislar límites genuinamente costosos, no deterministas o inseguros. Evita aserciones sobre llamadas a métodos privados o redacción exacta del código fuente a menos que esos sean en sí mismos el contrato.
Verifica los casos límite significativos: entradas mal formadas, datos vacíos, fallo de recursos y concurrencia o escrituras parciales cuando sea relevante. No prescribas un porcentaje de cobertura arbitrario o un conjunto completo para cada edición.
Preserva la compatibilidad pública a menos que cambiarla esté dentro del alcance. Para contratos duraderos y datos persistidos, examina los consumidores, el orden de despliegue, la migración y la recuperación. Usa expandir/contraer u otro enfoque escalonado cuando las versiones antigua y nueva deban coexistir; un cambio atómico coordinado puede ser suficiente en caso contrario. No elimines rutas de recuperación ni instales parches de compatibilidad sin un requisito real.
Verificación final de decisión
Antes de declarar la finalización, pregúntate:
- ¿Satisface la implementación el contrato real, incluyendo los fallos relevantes?
- ¿Está justificada cada abstracción, dependencia y archivo cambiado por esta tarea?
- ¿Puede un mantenedor localizar la regla, el propietario de su estado y la evidencia que la protege?
- ¿Preservé el comportamiento existente o hice explícito el cambio previsto en todos los consumidores afectados?
- ¿Qué verifiqué realmente, y qué queda sin verificar?
Usa esta verificación de forma privada; no emitas un informe estándar ni una puntuación de principios para cada edición.