S1_Calidad_del_Software - SofiAlfonso/croody_web3_project GitHub Wiki

Calidad del Software — Sprint 1

1. Estándares de Nombramiento

Convención adoptada

El proyecto sigue las convenciones estándar de la comunidad React/TypeScript y Solidity:

Elemento Convención Ejemplo
Componentes React PascalCase DashboardClient, ActionModal
Archivos de componentes PascalCase.tsx HomeClient.tsx, AppHeader.tsx
Hooks personalizados camelCase con prefijo use useWallet, useNfts, useAuctions
Variables y funciones camelCase isConnected, handleBid
Constantes UPPER_SNAKE_CASE MOCK_NFTS, SEPOLIA_CHAIN_ID
Tipos e interfaces PascalCase NFT, Auction, WalletContextType
Carpetas kebab-case o lowercase shared/, dashboard/, home/
CSS custom properties kebab-case con prefijo --gator-green, --jungle-dark
Contratos Solidity PascalCase ProjectToken, NFTCollection, NFTMarketplace
Funciones Solidity camelCase placeBid, endAuction
Eventos Solidity PascalCase AuctionCreated, BidPlaced

Justificación

  • React/TypeScript: se siguen las convenciones oficiales del React Style Guide y las recomendaciones de la comunidad TypeScript. PascalCase para componentes es el estándar de facto en el ecosistema React.
  • Solidity: se sigue la Solidity Style Guide oficial y las convenciones de OpenZeppelin.
  • Consistencia: todo el equipo utiliza las mismas convenciones, lo que facilita la lectura y mantenimiento del código.

Referencias

2. Análisis Estático de Código

Herramienta: ESLint v9

¿Qué es? ESLint es la herramienta de análisis estático de código más utilizada en el ecosistema JavaScript/TypeScript. Analiza el código fuente para encontrar patrones problemáticos, errores potenciales y violaciones de estilo.

Configuración actual:

  • Formato: Flat Config (nuevo estándar de ESLint 9+)
  • Archivo: eslint.config.mjs
  • Extends:
    • eslint-config-next/core-web-vitals — reglas de rendimiento y accesibilidad de Next.js
    • eslint-config-next/typescript — reglas específicas para TypeScript
  • Reglas personalizadas:
    • @typescript-eslint/no-unused-vars: warn — advierte sobre variables no usadas (ignora las que inician con _)

Comando de ejecución:

npm run lint

Justificación:

  • ESLint es la herramienta recomendada oficialmente por Next.js y la comunidad React.
  • La configuración core-web-vitals asegura cumplimiento con las métricas de rendimiento web de Google.
  • Las reglas de TypeScript ayudan a detectar errores de tipos y patrones inseguros.
  • Soporta corrección automática de errores (--fix), lo que también funciona como formateador de código para ciertos patrones.

Herramienta: Prettier v3.8

¿Qué es? Prettier es un formateador de código que asegura un estilo consistente en todo el proyecto, eliminando debates sobre formato.

Configuración actual (.prettierrc):

{
  "semi": true,
  "singleQuote": false,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 100,
  "plugins": ["prettier-plugin-tailwindcss"]
}

Características:

  • Punto y coma obligatorio
  • Comillas dobles (consistente con JSX)
  • Indentación de 2 espacios
  • Trailing commas en todos los contextos (mejor para diffs de Git)
  • Ancho máximo de línea: 100 caracteres
  • Plugin de Tailwind CSS (prettier-plugin-tailwindcss): ordena automáticamente las clases de Tailwind siguiendo el orden recomendado oficial

Justificación:

  • Prettier es el formateador más utilizado en el ecosistema JavaScript/TypeScript.
  • Elimina la necesidad de discutir estilos de formato en code reviews.
  • El plugin de Tailwind asegura consistencia en el orden de clases CSS utilitarias.

Herramienta: Solhint (Linter para Solidity)

¿Qué es? Solhint es la herramienta de análisis estático para contratos inteligentes en Solidity. Verifica buenas prácticas, seguridad y estilo de código.

Configuración actual (contracts/.solhint.json):

{
  "extends": "solhint:recommended",
  "rules": {
    "compiler-version": ["error", "^0.8.24"],
    "avoid-suicide": "error",
    "avoid-sha3": "error",
    "no-empty-blocks": "warn",
    "func-visibility": ["warn", { "ignoreConstructors": true }],
    "reason-string": ["warn", { "maxLength": 64 }],
    "func-name-mixedcase": "error",
    "var-name-mixedcase": "error",
    "use-natspec": "off"
  }
}

Comando de ejecución:

cd contracts && npm run lint

Reglas destacadas:

  • compiler-version: ^0.8.24 — asegura compatibilidad con la versión del compilador
  • avoid-suicide / avoid-sha3 — previene uso de funciones deprecadas e inseguras
  • func-name-mixedcase / var-name-mixedcase — enforza los estándares de nombramiento de Solidity
  • func-visibility — obliga a declarar visibilidad en funciones
  • reason-string — limita la longitud de mensajes de error (gas optimization)

Justificación:

  • Solhint es la herramienta estándar recomendada por la comunidad Solidity y Ethereum Foundation.
  • La configuración solhint:recommended incluye reglas de seguridad y buenas prácticas.
  • Las reglas de nombramiento refuerzan automáticamente las convenciones documentadas en la sección 1.

Punto adicional: los estándares de nombramiento de Solidity son enforzados por Solhint (func-name-mixedcase, var-name-mixedcase), garantizando cumplimiento automático.

TypeScript Strict Mode

Además de las herramientas anteriores, el proyecto tiene TypeScript en modo estricto ("strict": true en tsconfig.json), lo que habilita:

  • strictNullChecks — previene errores por valores null o undefined
  • strictFunctionTypes — verifica tipos de parámetros en funciones
  • noImplicitAny — obliga a declarar tipos explícitamente
  • noImplicitReturns — asegura que todas las ramas de una función retornen un valor

Resumen de herramientas de análisis estático

Herramienta Alcance Comando Corrección automática
ESLint v9 Frontend (TypeScript/React) npm run lint Sí (--fix)
Prettier v3.8 Frontend (formato de código) npx prettier --check . Sí (--write)
Solhint v6 Smart Contracts (Solidity) cd contracts && npm run lint No
TypeScript strict Frontend (tipos) npx tsc --noEmit No

3. Extras

3.1 Branching Strategy: GitHub Flow

El proyecto utiliza GitHub Flow como estrategia de branching:

main ─────────────────────────────────────────►
  │                                    ▲
  └──► develop ──────────────────────► │
         │              ▲              │
         └── feature/* ─┘              │
Rama Propósito
main Código en producción, estable
develop Rama de integración para desarrollo activo
feature/* Ramas individuales por funcionalidad o HU

Flujo de trabajo:

  1. Se crea una rama feature/* desde develop
  2. Se desarrolla la funcionalidad
  3. Se abre un Pull Request hacia develop
  4. Se hace code review y se aprueba
  5. Se mergea a develop
  6. Periódicamente se mergea develop a main para releases estables

Justificación: GitHub Flow es simple, ampliamente adoptado y adecuado para equipos pequeños con ciclos de desarrollo ágiles. La adición de develop como rama intermedia permite estabilizar features antes de llevarlas a producción.

3.2 Pipeline de Integración Continua (CI)

Estado: Pendiente de configuración. Se planea implementar un workflow de GitHub Actions que ejecute:

  • npm run lint — análisis estático
  • npm run build — verificación de compilación
  • Bloqueo de merge en PRs hasta que el pipeline esté en "green" y tenga al menos un approval

3.3 Herramientas de Seguridad

Estado: Pendiente. Se planea integrar:

  • npm audit para detección de vulnerabilidades en dependencias
  • Slither o MythX para análisis de seguridad de contratos Solidity