Guía de Estilo de Programación - Alejoso/Flujo-de-compras GitHub Wiki

Esta guía define las reglas de formato y estilo que deben seguirse durante el desarrollo del proyecto. El objetivo es mantener un código limpio, consistente y mantenible en todo el equipo.

1. Herramientas de Formato

Formato de Plantillas Blade

Para mantener un formato consistente en las plantillas Blade de Laravel (.blade.php), instalar la siguiente extensión de VS Code:

  • shufo.vscode-blade-formatter – Formatea automáticamente los archivos Blade para mejorar la legibilidad y mantener la consistencia.

Después de instalar, VS Code formateará los archivos Blade al guardar si tienes habilitado Format On Save.

Laravel Pint

El proyecto usará Laravel Pint para aplicar automáticamente las convenciones de estilo recomendadas para proyectos Laravel y PHP.

Laravel Pint está basado en PHP-CS-Fixer y sigue principalmente el estándar PSR-12.

Ejecutar Pint

Para formatear el código, ejecutar:

./vendor/bin/pint

Esto corregirá automáticamente los problemas de estilo en los archivos PHP.

Recomendación

Antes de hacer un commit, se recomienda ejecutar Pint para asegurarse de que el código sigue el estilo del proyecto.

2. Convenciones de Nomenclatura

Para mantener consistencia en el código, se deben seguir las siguientes reglas.

Clases

Usar PascalCase

Ejemplo:

ProductController
OrderService
UserController

Métodos y Funciones

Usar camelCase

Ejemplo:

getProducts()
calculateTotal()
generateInvoice()

Variables

Usar camelCase

Ejemplo:

$totalPrice
$userName
$productList

Constantes

Usar UPPER_CASE

Ejemplo:

DB_CONNECTION
DB_HOST

3. Organización del Código

Se deben respetar las convenciones de Laravel.

Controladores

Ubicación:

app/Http/Controllers

Modelos

Ubicación:

app/Models

Vistas

Ubicación:

resources/views

Reglas:

  • Usar Blade
  • Evitar lógica compleja dentro de las vistas
  • Usar layouts para reutilizar la estructura

4. Reglas de Indentación

El proyecto sigue estas reglas de indentación:

  • 4 espacios por nivel de indentación
  • Espacios en lugar de tabulaciones
  • Alineación consistente de bloques

Ejemplo:

public function about()
{
    return view('home.about');
}

5. Reglas de Importación (Use Statements)

Todas las importaciones PHP deben declararse al inicio del archivo usando use.

Ejemplo:

use App\Models\Product;
use App\Services\OrderService;
use Illuminate\Http\Request;

Reglas:

  • Evitar importaciones innecesarias
  • Agrupar las importaciones de forma lógica
  • No usar nombres de clase completamente calificados dentro del código si las importaciones están definidas

6. Principios de Desarrollo

Durante el desarrollo se deben aplicar los siguientes principios.

DRY (Don't Repeat Yourself)

Evitar duplicar código.
Si una funcionalidad se repite, debe reutilizarse mediante funciones o clases.

ETC (Easier To Change)

El código debe escribirse de manera que sea fácil de modificar en el futuro.

Inversión de Dependencias

Los módulos de alto nivel no deben depender directamente de los módulos de bajo nivel.
En su lugar, ambos deben depender de abstracciones (por ejemplo, interfaces).

7. Buenas Prácticas de Commits

Los commits deben describir claramente los cambios realizados para que cualquier persona que lea el historial pueda entender qué se hizo y por qué.

Tipos de Commit Recomendados

  • feat: Una nueva funcionalidad
  • fix: Corrección de un error
  • docs: Cambios en la documentación

Ejemplos

feat: agregar funcionalidad de búsqueda de productos en la página del catálogo
fix: prevenir órdenes vacías en la lógica de validación de OrderController
docs: actualizar README con nuevas instrucciones de instalación
feat: implementar paginación en la página de listado de productos
fix: corregir el cálculo del precio total en OrderService
docs: agregar guías de estilo de código para controladores y modelos