bf304f08fc
Agrega propiedades flexbox al contenedor .hero-section para que el contenido (título y badges) se muestre centrado verticalmente cuando no hay badges de categorías. Cambios: - display: flex - align-items: center - justify-content: center También incluye specs OpenSpec para arquitectura del tema. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
351 lines
12 KiB
Markdown
351 lines
12 KiB
Markdown
# 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
|