| name | Clean Code |
| description | Guía definitiva para escribir código limpio, legible y mantenible según el Protocolo Antigravity. |
🚀 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:
- Métodos de
C.
- Objetos creados por
f.
- Argumentos de
f.
- 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
- SRP (Single Responsibility): Una clase, una razón para cambiar.
- OCP (Open/Closed): Abierto a extensión, cerrado a modificación.
- LSP (Liskov Substitution): Subclases deben ser sustituibles por sus padres.
- ISP (Interface Segregation): Interfaces pequeñas específicas > Interfaces grandes generales.
- 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:
🤖 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).
