🚀 Protocolo Antigravity: Skill Clean Code

Versión: 1.0.0 Objetivo: Gravedad Cero (Eliminación total de deuda técnica y fricción cognitiva). Mandato Principal: El código se escribe para humanos primero, para máquinas después.

Esta Skill define las directrices obligatorias para cualquier código escrito en este proyecto.

📋 1. Nomenclatura: Semántica y Claridad

Los nombres son la interfaz de usuario del código.

1.1. Intención Revelada

El nombre debe responder: ¿Por qué existe? ¿Qué hace? ¿Cómo se usa?

• •❌ Incorrecto: var d; // días transcurridos
• •✅ Correcto: var daysSinceModification;

1.2. Evitar Desinformación

No usar términos técnicos (List, Map) si la estructura no lo es. Evitar prefijos/sufijos redundantes.

• •❌ Incorrecto: accountList (si no es una List), IUser ( interfaz), CUser (clase).
• •✅ Correcto: accounts, User, UserImpl.

1.3. Pronunciabilidad y Búsqueda

Los nombres deben ser pronunciables y fáciles de buscar (Greppable).

• •❌ Incorrecto: genymdhms (Generation Year Month Day...)
• •✅ Correcto: generationTimestamp

1.4. Convenciones de Naming

• •Clases/Tipos: PascalCase (Sustantivos, ej. Customer, WikiPage).
• •Métodos/Funciones: camelCase (Verbos, ej. postPayment, deletePage).
• •Constantes: UPPER_SNAKE_CASE (ej. MAX_RETRY_COUNT).
• •Variables/Propiedades: camelCase.
• •Archivos: Acorde al framework (ej. React: PascalCase componentes, camelCase hooks/utils).

⚡ 2. Funciones: Átomos de Lógica

2.1. Pequeñas y de Responsabilidad Única (SRP)

Una función debe hacer una sola cosa, hacerla bien y hacerla solo ella.

• •Si puedes extraer otra función de su interior con un nombre lógico, tu función original es demasiado grande.

2.2. Niveles de Abstracción

Regla del Paso Descendente: El código debe leerse como un periódico, de lo más importante a los detalles.

• •Una función no debe mezclar lógica de negocio (Alto Nivel) con detalles de implementación (Bajo Nivel, ej. SQL, HTML strings).

2.3. Argumentos

• •0 Argumentos: Ideal.
• •1-2 Argumentos: Aceptable.
• •3+ Argumentos: 🚩 Refactorizar. Encapsular en un objeto de contexto o configuración.
• •Flag Arguments: JAMÁS pases un booleano (render(true)). Divide la función (renderForSuite() y renderSingle()).

2.4. Pureza y Efectos Secundarios

Evita modificar variables globales o argumentos pasados por referencia si no es explícito.

• •Query/Command Separation: Una función debe hacer algo (Command) o responder algo (Query), pero no ambas.

📝 3. Comentarios

El código limpio se explica a sí mismo. Un comentario es a menudo una disculpa por no haber escrito un código más claro.

3.1. Prohibidos

• •Redundantes: i++; // incrementa i
• •Código comentado: Bórralo. Git es tu historia.
• •Marcadores: //////////// (Ruido visual).
• •Cierre: } // end if

3.2. Permitidos / Obligatorios

• •TODO: Notas de deuda técnica (usar formato // TODO: descripción).
• •Explicación de "Por qué" (no "Qué"): Justificar decisiones no obvias o workarounds necesarios.
• •Advertencias: "Este test es lento por X razón".

🧱 4. Objetos, Estructuras y Ley de Demeter

4.1. Abstracción

No expongas detalles de implementación.

• •❌ Incorrecto: getGallons()
• •✅ Correcto: getFuelPercentage()

4.2. Ley de Demeter (No hables con extraños)

Un método f de la clase C solo debe llamar a:

1. •Métodos de C.
2. •Objetos creados por f.
3. •Argumentos de f.
4. •Variables de instancia de C.

• •Evitar Train Wrecks: ctx.getOptions().getScratchDir().getAbsolutePath()

🛡️ 5. Manejo de Errores

5.1. Excepciones > Códigos de Error

Usa Excepciones. No ensucies la lógica principal con nidos de if (err != null).

5.2. No Nulos

• •No devuelvas Null: Devuelve Array vacío, Optional, o Null Object Pattern.
• •No pases Null: Asume que los argumentos no son null a menos que se especifique lo contrario (defensive programming).

🏗️ 6. Arquitectura SOLID

1. •SRP (Single Responsibility): Una clase, una razón para cambiar.
2. •OCP (Open/Closed): Abierto a extensión, cerrado a modificación.
3. •LSP (Liskov Substitution): Subclases deben ser sustituibles por sus padres.
4. •ISP (Interface Segregation): Interfaces pequeñas específicas > Interfaces grandes generales.
5. •DIP (Dependency Inversion): Depende de abstracciones, no de concreciones.

🧪 7. Testing

El código sin test es deuda técnica instantánea.

• •F.I.R.S.T.: Fast, Independent, Repeatable, Self-Validating, Timely.
• •Un Assert por Test: Prueba un solo concepto lógico por test.
• •Separación: Tests unitarios, Tests de integración, Tests E2E.

✅ Checklist de Auto-Revisión

Antes de dar una tarea por terminada, verifica:

• • ¿Los nombres revelan intención?
• • ¿Funciones < 20 líneas (aprox) y hacen una sola cosa?
• • ¿No hay números mágicos ni strings hardcodeados?
• • ¿Manejo de errores robusto (sin try/catch vacíos)?
• • ¿Tests cubren funcionalidad principal y edge cases?
• • ¿Tests cubren funcionalidad principal y edge cases?
• • ¿Código formateado consistentemente?

🤖 8. Automatización

El "Clean Code" también es código estandarizado.

• •Usa Prettier para no discutir sobre espacios vs tabs.
• •Usa ESLint para atrapar errores antes de que ocurran.
• •Si el linter se queja, el código está sucio. Corrígelo, no lo ignores (eslint-disable solo con justificación escrita).