Guía de Estilos - NSaldarriagaV/Ctrl-Store GitHub Wiki

Guía de Estilo y Reglas de Programación

Proyecto: Ctrl+Store

1) Guía de estilo de codificación (inventada para el proyecto)

1.1 Principios generales

  • Legibilidad > ingenio: prioriza código claro y explícito.
  • Consistencia: si hay varias formas correctas, usa la del proyecto.
  • “Thin Views, Fat Services”: vistas delgadas, la lógica de negocio vive en services/.
  • Inmutabilidad por defecto: evita mutar estructuras salvo que sea necesario.
  • Idempotencia en operaciones críticas (pagos, generación de factura).

1.2 Formato y herramientas

  • Formateo: black (línea 100), imports: isort, lint: ruff, tipado: mypy.
  • Nombres:
    • módulos/paquetes: snake_case; clases: PascalCase; funciones/variables: snake_case;
    • constantes: UPPER_SNAKE; templates: kebab-case.html.
  • Commits Git: tipo(scope): resumen (feat, fix, refactor, test, docs, chore).

1.3 Organización del proyecto

ctrlstore/ settings/ apps/ auth/ catalog/ cart/ order/ payment/ billing/ analytics/ common/

  • No mezclar responsabilidades entre apps.
  • settings 12-factor: variables sensibles por entorno, nunca en repo.

1.4 Tipos y errores

  • Tipado con mypy.
  • Usa dataclasses o TypedDict.
  • Errores de negocio → excepciones propias (PaymentError, StockError).

2) Reglas esenciales por categoría

2.1 Rutas (urls)

  1. Toda ruta debe estar asociada a un View.
  2. Usa namespaces (app_name).
  3. Nombres consistentes: catalog:product_detail.
  4. Nunca hardcodear URLs en templates.
  5. Agrupar rutas en cada app.
  6. Usar reverse_lazy en redirecciones.

2.2 Vistas (controllers)

  1. Preferir Class Based Views para CRUD.
  2. Mantener vistas delgadas.
  3. Autenticación y permisos claros.
  4. Contexto mínimo y explícito.
  5. Respuestas correctas: 404, 403, 400.
  6. Evitar N+1 queries.
  7. Paginación obligatoria en listados.
  8. CSRF activo en POST.

2.3 Modelos

  1. Dinero → DecimalField.
  2. Implementar __str__ y constraints.
  3. Validación en clean().
  4. Operaciones críticas en transaction.atomic().
  5. QuerySets personalizados.
  6. Índices en campos clave.
  7. Signals con moderación.

2.4 Formularios / Serializers

  1. Validación en formularios, no en vistas.
  2. Errores claros.
  3. Nunca guardar datos sensibles de tarjeta.
  4. Validadores centralizados.

2.5 Templates

  1. Todas las vistas extienden base.html.
  2. Templates siempre en HTML.
  3. Nada de lógica de negocio.
  4. Accesibilidad básica.
  5. CSS organizados en static/.

2.6 Servicios

  1. Lógica pesada en services/.
  2. Idempotencia obligatoria.

2.7 Seguridad

  1. CSRF siempre activo.
  2. Escapar variables → evitar XSS.
  3. Passwords con algoritmos fuertes.
  4. Permisos de objeto: un cliente solo ve lo suyo.

2.8 Observabilidad

  1. Logging estructurado.
  2. Logs con user_id, order_id, payment_id.

2.9 Migraciones y datos

  1. Una migración por cambio de modelo.

3) Reglas esenciales (resumen)

  • Toda ruta tiene View.
  • Toda vista extiende base.html.
  • Todos los templates son HTML.
  • Precios con Decimal.
  • Vistas delgadas, lógica en services.
  • Operaciones críticas en transacción.
  • Pagos y facturas idempotentes.
  • Logs estructurados con IDs de negocio.