# Especificacion de Estandares de Codigo

## Purpose

Define los principios SOLID, estandares de POO (Programacion Orientada a Objetos) y estandares generales de codigo que DEBEN seguirse en el desarrollo de ROITheme.

## Requirements

### Requirement: Principio de Responsabilidad Unica (SRP)

Each class MUST have exactly one reason to change and one responsibility.

#### Scenario: Responsabilidad de clase Use Case
- **WHEN** se crea una clase Use Case
- **THEN** DEBE manejar exactamente UNA operacion (Save, Get, Delete, etc.)
- **AND** NO DEBE combinar multiples operaciones en una clase

#### Scenario: Validacion de tamano de clase
- **WHEN** se crea un archivo de clase
- **THEN** DEBERIA tener menos de 300 lineas
- **AND** DEBERIA tener maximo 3-5 metodos privados
- **AND** el nombre de la clase DEBE describir su unica responsabilidad

#### Scenario: Violacion de SRP
- **WHEN** una clase contiene save(), get(), delete(), validate(), sendEmail()
- **THEN** DEBE dividirse en clases Use Case separadas
- **AND** cada clase maneja solo una operacion

---

### Requirement: Principio Abierto/Cerrado (OCP)

Classes MUST be open for extension but closed for modification.

#### Scenario: Agregar nuevo tipo de componente
- **WHEN** se necesita un nuevo tipo de componente
- **THEN** se DEBE crear una nueva subclase
- **AND** la clase BaseComponent existente NO DEBE modificarse
- **AND** NO se DEBERIAN agregar cadenas if/elseif para nuevos tipos

#### Scenario: Extender funcionalidad base
- **GIVEN** que existe una clase abstracta BaseComponent
- **WHEN** se necesita comportamiento especializado
- **THEN** se DEBE usar herencia para extender
- **AND** la clase base DEBE permanecer sin cambios

---

### Requirement: Principio de Sustitucion de Liskov (LSP)

Subclasses MUST be substitutable for their base classes without breaking functionality.

#### Scenario: Uso polimorfico
- **GIVEN** una funcion que acepta parametro BaseComponent
- **WHEN** cualquier subclase es pasada
- **THEN** la funcion DEBE funcionar correctamente
- **AND** NO se DEBERIAN lanzar excepciones inesperadas

#### Scenario: Cumplimiento de contrato
- **WHEN** una subclase sobrescribe un metodo padre
- **THEN** DEBE respetar el contrato del metodo original
- **AND** las precondiciones NO DEBEN ser mas restrictivas
- **AND** las postcondiciones NO DEBEN ser mas permisivas

---

### Requirement: Principio de Segregacion de Interfaces (ISP)

Interfaces MUST be small and specific, not large and general.

#### Scenario: Validacion de tamano de interface
- **WHEN** se define una interface
- **THEN** DEBE tener maximo 3-5 metodos
- **AND** cada metodo DEBE relacionarse con la misma capacidad

#### Scenario: Evitar interfaces gordas
- **WHEN** existen multiples capacidades no relacionadas
- **THEN** se DEBEN crear interfaces separadas
- **AND** las clases implementan solo las interfaces que usan
- **AND** NO se permiten metodos dummy "No implementado"

#### Scenario: Diseno correcto de interface
- **WHEN** se necesita funcionalidad de cache
- **THEN** se DEBE usar CacheInterface con get(), set(), delete()
- **AND** ValidatorInterface con validate() es separada

---

### Requirement: Principio de Inversion de Dependencias (DIP)

High-level modules MUST depend on abstractions, not concrete implementations.

#### Scenario: Inyeccion por constructor con interfaces
- **WHEN** una clase necesita dependencias
- **THEN** el constructor DEBE recibir interfaces, NO clases concretas
- **AND** NO debe haber new ClaseConcreta() dentro del cuerpo de la clase

#### Scenario: Cableado del Contenedor DI
- **WHEN** se necesitan implementaciones concretas
- **THEN** el DIContainer DEBE manejar el cableado
- **AND** las clases permanecen desacopladas de las implementaciones

#### Scenario: Dependencia incorrecta
- **WHEN** el constructor hace this->repo = new WordPressNavbarRepository()
- **THEN** esto DEBE refactorizarse para recibir NavbarRepositoryInterface
- **AND** el DIContainer proporciona la implementacion concreta

---

### Requirement: Encapsulacion de Propiedades

Class properties MUST be encapsulated with controlled access.

#### Scenario: Visibilidad de propiedades
- **WHEN** se define una propiedad de clase
- **THEN** DEBE ser private o protected
- **AND** el acceso DEBE ser via metodos getter
- **AND** la mutacion DEBE ser via metodos setter o metodos de negocio

#### Scenario: Encapsulacion de Value Object
- **GIVEN** un ValueObject como ComponentName
- **WHEN** es construido
- **THEN** la validacion DEBE ocurrir en el constructor
- **AND** el valor DEBE ser inmutable despues de la construccion
- **AND** los detalles internos NO DEBEN exponerse

---

### Requirement: Guias de Herencia

Inheritance MUST be used appropriately with limited depth.

#### Scenario: Limite de profundidad de herencia
- **WHEN** se usa herencia
- **THEN** la profundidad maxima DEBE ser 2-3 niveles
- **AND** las cadenas de herencia profundas DEBEN evitarse

#### Scenario: Comportamiento comun en clase base
- **WHEN** multiples clases comparten comportamiento comun
- **THEN** se DEBERIA crear una clase base abstracta
- **AND** las subclases especializan con comportamiento adicional

---

### Requirement: Polimorfismo Correcto

Methods MUST accept base types or interfaces to enable polymorphism.

#### Scenario: Tipos de parametros de metodo
- **WHEN** un metodo acepta parametro de componente
- **THEN** el type hint DEBERIA ser BaseComponent o ComponentInterface
- **AND** cualquier subclase/implementacion DEBE funcionar correctamente

#### Scenario: Polimorfismo de repository
- **WHEN** un Use Case usa un repository
- **THEN** DEBE aceptar RepositoryInterface
- **AND** WordPressRepository y MockRepository funcionan transparentemente

---

### Requirement: Estandares PHP Estrictos

All PHP code MUST follow strict type safety and naming conventions.

#### Scenario: Declaracion de tipos estrictos
- **WHEN** se crea un archivo PHP
- **THEN** DEBE comenzar con declare(strict_types=1)
- **AND** los tipos de retorno DEBEN declararse
- **AND** los tipos de parametros DEBEN declararse

#### Scenario: Convencion de namespace
- **WHEN** se crea una clase
- **THEN** el namespace DEBE seguir ROITheme\[Contexto]\[Componente]\[Capa]
- **AND** DEBE soportar autoloading PSR-4

#### Scenario: Declaracion de clase
- **WHEN** se crea una clase
- **THEN** DEBERIA ser final por defecto
- **AND** solo hacerla no-final cuando se pretende herencia
- **AND** el nombre de clase DEBE ser PascalCase

---

### Requirement: Modularidad del Codigo

Code MUST be organized into independent and cohesive modules.

#### Scenario: Independencia de modulos
- **WHEN** se crea un modulo
- **THEN** DEBE ser autocontenido
- **AND** NO DEBE depender de otros modulos (solo de Shared/)
- **AND** eliminarlo NO DEBE romper otros modulos

#### Scenario: Alta cohesion
- **WHEN** el codigo se coloca en un modulo
- **THEN** todo el codigo DEBE relacionarse con el proposito de ese modulo
- **AND** el codigo no relacionado DEBE estar en Shared/ u otro modulo

#### Scenario: Bajo acoplamiento
- **WHEN** los modulos interactuan
- **THEN** DEBEN comunicarse a traves de interfaces de Shared/
- **AND** las dependencias directas entre modulos estan prohibidas

---

### Requirement: DRY - No Te Repitas

Code duplication MUST be eliminated through appropriate abstraction.

#### Scenario: Ubicacion de codigo compartido
- **WHEN** el codigo es usado por multiples modulos
- **THEN** DEBE moverse al nivel apropiado de Shared/
- **AND** los modulos DEBEN importar de Shared/

#### Scenario: Deteccion de duplicacion
- **WHEN** existe codigo similar en 2+ lugares
- **THEN** DEBE refactorizarse a Shared/
- **AND** las ubicaciones originales importan de Shared/

---

### Requirement: KISS - Mantenlo Simple

Solutions MUST be simple and avoid over-engineering.

#### Scenario: Uso de patrones
- **WHEN** se considera un patron de diseno
- **THEN** DEBE resolver un problema real
- **AND** se DEBEN preferir soluciones mas simples
- **AND** la abstraccion excesiva DEBE evitarse

#### Scenario: Claridad del codigo
- **WHEN** se escribe codigo
- **THEN** DEBERIA ser auto-documentado
- **AND** los comentarios DEBERIAN ser innecesarios para entender
- **AND** la logica compleja DEBERIA extraerse a metodos bien nombrados

---

### Requirement: Separacion de Responsabilidades por Capa

Each layer MUST have distinct responsibilities.

#### Scenario: Responsabilidades por capa
- **WHEN** se escribe codigo
- **THEN** Domain contiene logica de negocio
- **AND** Application contiene orquestacion
- **AND** Infrastructure contiene implementacion tecnica
- **AND** UI contiene solo presentacion

#### Scenario: Validacion de responsabilidades cruzadas
- **WHEN** se valida ubicacion de codigo
- **THEN** SQL NO DEBE estar en Domain/Application
- **AND** HTML NO DEBE estar en Domain/Application
- **AND** logica de negocio NO DEBE estar en Infrastructure

---

### Requirement: Limites de Tamano de Archivo

Files MUST be kept small and focused.

#### Scenario: Tamano de archivo de clase
- **WHEN** se crea un archivo de clase
- **THEN** DEBERIA tener menos de 300 lineas
- **AND** si es mas grande, DEBERIA dividirse en clases mas pequenas

#### Scenario: Tamano de metodo
- **WHEN** se escribe un metodo
- **THEN** DEBERIA tener menos de 30 lineas
- **AND** metodos complejos DEBERIAN extraerse a metodos auxiliares

---

### Requirement: Convenciones de Nomenclatura

Names MUST be clear, descriptive, and follow conventions.

#### Scenario: Nomenclatura de clases
- **WHEN** se nombra una clase
- **THEN** el nombre DEBE describir su unica responsabilidad
- **AND** las clases Use Case DEBEN nombrarse [Accion][Entidad]UseCase
- **AND** las clases Repository DEBEN nombrarse [Implementacion][Entidad]Repository

#### Scenario: Nomenclatura de metodos
- **WHEN** se nombra un metodo
- **THEN** DEBE describir lo que hace el metodo
- **AND** DEBERIA comenzar con un verbo
- **AND** metodos booleanos DEBERIAN comenzar con is/has/can

#### Scenario: Nomenclatura de variables
- **WHEN** se nombra una variable
- **THEN** DEBE ser descriptiva
- **AND** las abreviaturas DEBEN evitarse
- **AND** nombres de una letra solo para contadores de bucle

---

### Requirement: Validacion Pre-Commit

Code MUST pass validation before commit.

#### Scenario: Verificacion de cumplimiento SOLID
- **WHEN** el codigo esta listo para commit
- **THEN** SRP cada clase tiene una responsabilidad
- **AND** OCP nuevas caracteristicas via extension, no modificacion
- **AND** LSP las subclases son sustituibles
- **AND** ISP las interfaces son pequenas 3-5 metodos
- **AND** DIP el constructor recibe interfaces

#### Scenario: Verificacion de cumplimiento POO
- **WHEN** el codigo esta listo para commit
- **THEN** las propiedades son private/protected
- **AND** la profundidad de herencia es max 2-3 niveles
- **AND** el polimorfismo esta implementado correctamente
- **AND** la abstraccion oculta complejidad

#### Scenario: Verificacion de calidad
- **WHEN** el codigo esta listo para commit
- **THEN** los archivos tienen menos de 300 lineas
- **AND** los nombres son claros y descriptivos
- **AND** no existe duplicacion de codigo
- **AND** no hay sobre-ingenieria presente

---

### Requirement: Escaping Obligatorio en Output HTML

All HTML output MUST use WordPress escaping functions for security.

#### Scenario: Escaping de textos
- **WHEN** se genera output de texto en HTML
- **THEN** DEBE usar esc_html() para contenido de texto

#### Scenario: Escaping de atributos
- **WHEN** se genera un atributo HTML
- **THEN** DEBE usar esc_attr() para valores de atributos

#### Scenario: Escaping de URLs
- **WHEN** se genera una URL en href o src
- **THEN** DEBE usar esc_url() para URLs

#### Scenario: Escaping de textareas
- **WHEN** se genera contenido para textarea
- **THEN** DEBE usar esc_textarea() para el valor

#### Scenario: Prohibicion de output sin escaping
- **WHEN** se revisa codigo de Renderer o FormBuilder
- **THEN** NO DEBE existir echo o print de variables sin escaping
- **AND** NO DEBE existir interpolacion directa de variables en HTML
