Convenciones de código

Este documento define las reglas de estilo de código para el proyecto Maius, aplicables a Laravel/PHP y React/JS/TS. El objetivo es garantizar consistencia, legibilidad y facilidad de mantenimiento.

---

🎯 Justificación de los estándares elegidos

• PSR-12 (PHP Standards Recommendations): es el estándar oficial definido por PHP-FIG. Es ampliamente adoptado en la comunidad Laravel, soportado por herramientas como PHP_CodeSniffer y asegura uniformidad en la indentación, nombres y estructura de clases.

• Airbnb JavaScript Style Guide: una de las guías de estilo más usadas en el ecosistema JS/React. Proporciona convenciones claras para nombres, estructuras de componentes y buenas prácticas de ES6+.

La combinación de ambos permite que los equipos trabajen en un mismo estilo independientemente del lenguaje.

---

📂 Archivos y carpetas

Laravel / PHP

• Controladores → PascalCaseController.php Ej: StudentController.php
• Modelos → PascalCase.php Ej: Student.php
• Servicios (lógica de negocio separada del controlador) → PascalCaseService.php Ej: PaymentService.php, ReportGeneratorService.php
• Repositorios → PascalCaseRepository.php Ej: StudentRepository.php
• Migraciones → snake_case_con_fecha.php Ej: 2025_09_03_create_users_table.php
• Vistas Blade → kebab-case.blade.php Ej: student-profile.blade.php

React / JS / TS

• Componentes → PascalCase.jsx/tsx Ej: StudentCard.jsx
• Hooks → useCamelCase.js Ej: useFetchUsers.js
• Archivos utilitarios → camelCase.js Ej: dateFormatter.js
• Carpetas → kebab-case/ Ej: student-profile/

---

🔡 Variables, funciones y clases

JS/TS

• Variables y funciones → camelCase Ej: studentName, getStudentInfo
• Constantes → UPPER_SNAKE_CASE Ej: MAX_RETRY_COUNT
• Clases y componentes → PascalCase Ej: StudentCard

PHP

• Variables y métodos → camelCase Ej: $studentName, getStudentInfo()
• Clases → PascalCase Ej: StudentController
• Constantes → UPPER_SNAKE_CASE

---

🛠 Funciones

• Deben describir acción con verbo:

  • ✅ getUser(), calculateGrade()
  • ❌ userData(), calc()

• En React → hooks siempre con prefijo use.

---

📝 Ejemplos

PHP (Controlador)

// ✅ Correcto
class StudentController {
    public function getStudentData() {}
    private $studentName;
}

// ❌ Incorrecto
class student_controller {
    public function Get_Student_Data() {}
    private $Student_name;
}

React (Componente)

// ✅ Correcto
function StudentCard({ studentName }) { ... }

// ❌ Incorrecto
function student_card({ Student_name }) { ... }

Laravel Service (lógica de negocio)

// ✅ Correcto
class PaymentService {
    public function processPayment(Student $student, Invoice $invoice) {
        // lógica del pago
    }
}

// ❌ Incorrecto
class CrudStudent {
    public function doStuff() {}
}

---

🔧 ESLint Configuración (Airbnb + ajustes)

Ejemplo de .eslintrc.json:

{
  "extends": ["airbnb", "airbnb/hooks", "prettier"],
  "plugins": ["react", "jsx-a11y", "import"],
  "rules": {
    "react/jsx-filename-extension": [1, { "extensions": [".js", ".jsx", ".ts", ".tsx"] }],
    "react/prop-types": "off",
    "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
    "camelcase": ["error", { "properties": "always" }],
    "import/prefer-default-export": "off",
    "class-methods-use-this": "off"
  },
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  }
}

---

📌 Recomendaciones adicionales

• Usar PHP_CodeSniffer con PSR-12 para validar código PHP/Laravel.
• Usar Prettier/Biome para formateo automático en React/JS/TS.
• Configurar Git Hooks (Husky + lint-staged) para evitar commits que no cumplan las reglas.

---