🤝 Guía de Contribución

Cómo contribuir al proyecto Fincos de forma efectiva

Estándares de Código

📝 Convenciones de Nomenclatura

camelCase

Variables, funciones, métodos: calculateTotalPrice, userData

PascalCase

Componentes React, clases: PropertyCard, BookingModule

UPPER_SNAKE_CASE

Constantes globales: MARKUP, MAX_FILE_SIZE

kebab-case

Rutas de archivos CSS: property-card.css

🎨 Estructura de Componentes React

import React, { useState, useEffect, useMemo } from "react";
import { Button } from "@/components/ui/button";

// Props con JSDoc para mejor DX
/**
 * @param {Object} props
 * @param {string} props.title - Título del componente
 * @param {Function} props.onSubmit - Callback al enviar
 */
export default function MyComponent({ title, onSubmit }) {
  // 1. Estado local
  const [data, setData] = useState(null);
  
  // 2. Valores derivados con useMemo
  const processedData = useMemo(() => {
    return data ? data.map(transform) : [];
  }, [data]);
  
  // 3. Efectos
  useEffect(() => {
    loadData();
  }, []);
  
  // 4. Handlers
  const handleClick = () => {
    onSubmit(processedData);
  };
  
  // 5. Early returns
  if (!data) return <div>Loading...</div>;
  
  // 6. JSX principal
  return (
    <div className="...">
      <h1>{title}</h1>
      <Button onClick={handleClick}>Submit</Button>
    </div>
  );
}

⚠️ Reglas Importantes

Nunca hacer console.log en producción sin razón

Nunca hardcodear datos sensibles (API keys, secrets)

Nunca modificar directamente el estado (siempre inmutable)

SÍ

Siempre usar TanStack Query para datos del servidor

SÍ

Siempre manejar estados de carga y error en la UI

SÍ

Siempre hacer componentes responsivos (mobile-first)

Workflow de Desarrollo

Identificar la tarea

Antes de empezar, entender completamente el objetivo. Leer la documentación relevante y verificar que no existe ya una solución.

Planificar la implementación

Identificar qué archivos necesitan modificarse. Para features complejas, desglosar en subtareas pequeñas.

Desarrollar incrementalmente

Hacer cambios pequeños y testear frecuentemente. Nunca acumular muchos cambios sin verificar que funcionan.

Testing manual

Probar la funcionalidad en múltiples escenarios:

• Happy path (caso ideal)
• Edge cases (límites, valores extremos)
• Error handling (errores esperados)
• Mobile y desktop

Code review (si aplica)

Revisar el propio código antes de enviar. Buscar código duplicado, complejidad innecesaria, console.logs olvidados, etc.

Documentar si es necesario

Para funcionalidades complejas o no obvias, agregar comentarios explicativos. Actualizar esta documentación si cambia la arquitectura.

Criterios de Calidad

Errores Comunes a Evitar

🚫 Modificar estado directamente

// ❌ MAL
user.name = "Nuevo nombre";
setUser(user);

// ✅ BIEN
setUser({...user, name: "Nuevo nombre"});

🚫 Olvidar manejar errores

// ❌ MAL
const data = await api.fetchData();

// ✅ BIEN
try {
  const data = await api.fetchData();
} catch (error) {
  console.error("Error fetching data:", error);
  showErrorToast(error.message);
}

🚫 Usar índices como keys en listas

// ❌ MAL
{items.map((item, index) => <div key={index}>{item.name}</div>)}

// ✅ BIEN
{items.map((item) => <div key={item.id}>{item.name}</div>)}

🚫 No limpiar efectos

// ❌ MAL
useEffect(() => {
  const interval = setInterval(doSomething, 1000);
}, []);

// ✅ BIEN
useEffect(() => {
  const interval = setInterval(doSomething, 1000);
  return () => clearInterval(interval);
}, []);

Recursos Útiles

📚 Documentación

🛠️ Herramientas

• Debug Info
• Tests de Pricing
• Validar Rutas
• React DevTools (extensión de navegador)

🎨 UI/UX

📞 Soporte

• WhatsApp: +57 318 422 7350
• Email: info@fincos.co
• Base44 Support