padrões-de-codificação

Padrões de Codificação & Melhores Práticas

Convenções básicas de codificação aplicáveis entre projetos.

Esta skill é o piso compartilhado, não o manual detalhado do framework.

• Use frontend-patterns para React, estado, formulários, renderização e arquitetura de UI.
• Use backend-patterns ou api-design para camadas de repositório/serviço, design de endpoints, validação e preocupações específicas do servidor.
• Use rules/common/coding-style.md quando precisar da camada de regras reutilizável mais curta em vez de uma explicação completa da skill.

Quando Ativar

• Iniciar um novo projeto ou módulo
• Revisar código para qualidade e manutenibilidade
• Refatorar código existente para seguir convenções
• Aplicar consistência de nomenclatura, formatação ou estrutura
• Configurar regras de linting, formatação ou verificação de tipos
• Integrar novos contribuidores às convenções de codificação

Limites de Escopo

Ative esta skill para:

• nomenclatura descritiva
• padrões de imutabilidade
• legibilidade, aplicação de KISS, DRY e YAGNI
• tratamento de erros e revisão de code smells

Não use esta skill como fonte principal para:

• composição, hooks ou padrões de renderização do React
• arquitetura de backend, design de API ou camadas de banco de dados
• orientação de framework específico quando uma skill ECC mais específica já existir

Princípios de Qualidade de Código

1. Legibilidade em Primeiro Lugar

• O código é mais lido do que escrito
• Nomes claros de variáveis e funções
• Código autodocumentado preferível a comentários
• Formatação consistente

2. KISS (Keep It Simple, Stupid - Mantenha Simples, Idiota)

• A solução mais simples que funciona
• Evite engenharia excessiva
• Sem otimização prematura
• Fácil de entender > código engenhoso

3. DRY (Don't Repeat Yourself - Não Se Repita)

• Extraia lógica comum em funções
• Crie componentes reutilizáveis
• Compartilhe utilitários entre módulos
• Evite programação copiar-colar

4. YAGNI (You Aren't Gonna Need It - Você Não Vai Precisar Disso)

• Não crie recursos antes de serem necessários
• Evite generalidade especulativa
• Adicione complexidade apenas quando necessário
• Comece simples, refatore quando precisar

Padrões TypeScript/JavaScript

Nomenclatura de Variáveis

// PASS: BOM: Nomes descritivos
const consultaMercadoPesquisa = 'eleição'
const usuarioEstaAutenticado = true
const receitaTotal = 1000

// FAIL: RUIM: Nomes pouco claros
const q = 'eleição'
const flag = true
const x = 1000

Nomenclatura de Funções

// PASS: BOM: Padrão verbo-substantivo
async function buscarDadosMercado(idMercado: string) { }
function calcularSimilaridade(a: number[], b: number[]) { }
function isEmailValido(email: string): boolean { }

// FAIL: RUIM: Pouco claro ou apenas substantivo
async function mercado(id: string) { }
function similaridade(a, b) { }
function email(e) { }

Padrão de Imutabilidade (CRÍTICO)

// PASS: SEMPRE use operador spread
const usuarioAtualizado = {
  ...usuario,
  nome: 'Novo Nome'
}

const arrayAtualizado = [...itens, novoItem]

// FAIL: NUNCA mude diretamente
usuario.nome = 'Novo Nome'  // RUIM
itens.push(novoItem)        // RUIM

Tratamento de Erros

// PASS: BOM: Tratamento de erros abrangente
async function buscarDados(url: string) {
  try {
    const resposta = await fetch(url)

    if (!resposta.ok) {
      throw new Error(`HTTP ${resposta.status}: ${resposta.statusText}`)
    }

    return await resposta.json()
  } catch (erro) {
    console.error('Falha na busca:', erro)
    throw new Error('Falha ao buscar dados')
  }
}

// FAIL: RUIM: Sem tratamento de erros
async function buscarDados(url) {
  const resposta = await fetch(url)
  return resposta.json()
}

Melhores Práticas Async/Await

// PASS: BOM: Execução paralela quando possível
const [usuarios, mercados, estatisticas] = await Promise.all([
  buscarUsuarios(),
  buscarMercados(),
  buscarEstatisticas()
])

// FAIL: RUIM: Sequencial quando desnecessário
const usuarios = await buscarUsuarios()
const mercados = await buscarMercados()
const estatisticas = await buscarEstatisticas()

Segurança de Tipos

// PASS: BOM: Tipos adequados
interface Mercado {
  id: string
  nome: string
  status: 'ativo' | 'resolvido' | 'fechado'
  criado_em: Date
}

function obterMercado(id: string): Promise<Mercado> {
  // Implementação
}

// FAIL: RUIM: Usando 'any'
function obterMercado(id: any): Promise<any> {
  // Implementação
}

Melhores Práticas React

Estrutura de Componentes

// PASS: BOM: Componente funcional com tipos
interface ButtonProps {
  children: React.ReactNode
  onClick: () => void
  disabled?: boolean
  variant?: 'primary' | 'secondary'
}

export function Button({
  children,
  onClick,
  disabled = false,
  variant = 'primary'
}: ButtonProps) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      className={`btn btn-${variant}`}
    >
      {children}
    </button>
  )
}

// FAIL: RUIM: Sem tipos, estrutura pouco clara
export function Button(props) {
  return <button onClick={props.onClick}>{props.children}</button>
}

Hooks Personalizados

// PASS: BOM: Hook personalizado reutilizável
export function useDebounce<T>(valor: T, atraso: number): T {
  const [valorComDebounce, setValorComDebounce] = useState<T>(valor)

  useEffect(() => {
    const handler = setTimeout(() => {
      setValorComDebounce(valor)
    }, atraso)

    return () => clearTimeout(handler)
  }, [valor, atraso])

  return valorComDebounce
}

// Uso
const consultaComDebounce = useDebounce(consultaPesquisa, 500)

Gerenciamento de Estado

// PASS: BOM: Atualizações de estado adequadas
const [contador, setContador] = useState(0)

// Atualização funcional para estado baseado no estado anterior
setContador(prev => prev + 1)

// FAIL: RUIM: Referência direta ao estado
setContador(contador + 1)  // Pode estar desatualizado em cenários assíncronos

Renderização Condicional

// PASS: BOM: Renderização condicional clara
{isCarregando && <Spinner />}
{erro && <ErrorMessage error={erro} />}
{dados && <DataDisplay data={dados} />}

// FAIL: RUIM: Inferno ternário
{isCarregando ? <Spinner /> : erro ? <ErrorMessage error={erro} /> : dados ? <DataDisplay data={dados} /> : null}

Padrões de Design de API

Convenções REST API

GET    /api/mercados              # Listar todos os mercados
GET    /api/mercados/:id          # Obter mercado específico
POST   /api/mercados              # Criar novo mercado
PUT    /api/mercados/:id          # Atualizar mercado (completo)
PATCH  /api/mercados/:id          # Atualizar mercado (parcial)
DELETE /api/mercados/:id          # Excluir mercado

# Parâmetros de consulta para filtragem
GET /api/mercados?status=ativo&limite=10&offset=0

Formato de Resposta

// PASS: BOM: Estrutura de resposta consistente
interface ApiResponse<T> {
  success: boolean
  data?: T
  error?: string
  meta?: {
    total: number
    page: number
    limit: number
  }
}

// Resposta de sucesso
return NextResponse.json({
  success: true,
  data: mercados,
  meta: { total: 100, page: 1, limit: 10 }
})

// Resposta de erro
return NextResponse.json({
  success: false,
  error: 'Requisição inválida'
}, { status: 400 })

Validação de Entrada

import { z } from 'zod'

// PASS: BOM: Validação de esquema
const CriarMercadoSchema = z.object({
  nome: z.string().min(1).max(200),
  descricao: z.string().min(1).max(2000),
  dataFinal: z.string().datetime(),
  categorias: z.array(z.string()).min(1)
})

export async function POST(request: Request) {
  const body = await request.json()

  try {
    const validated = CriarMercadoSchema.parse(body)
    // Prossiga com os dados validados
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json({
        success: false,
        error: 'Falha na validação',
        details: error.issues
      }, { status: 400 })
    }
  }
}

Organização de Arquivos

Estrutura do Projeto

src/
├── app/                    # Next.js App Router
│   ├── api/               # Rotas de API
│   ├── mercados/          # Páginas de mercado
│   └── (auth)/           # Páginas de autenticação (grupos de rotas)
├── components/            # Componentes React
│   ├── ui/               # Componentes de UI genéricos
│   ├── forms/            # Componentes de formulário
│   └── layouts/          # Componentes de layout
├── hooks/                # Hooks React personalizados
├── lib/                  # Utilitários e configurações
│   ├── api/             # Clientes de API
│   ├── utils/           # Funções auxiliares
│   └── constants/       # Constantes
├── types/                # Tipos TypeScript
└── styles/              # Estilos globais

Nomenclatura de Arquivos

components/Button.tsx          # PascalCase para componentes
hooks/useAuth.ts              # camelCase com prefixo 'use'
lib/formatDate.ts             # camelCase para utilitários
types/market.types.ts         # camelCase com sufixo .types

Comentários e Documentação

Quando Comentar

// PASS: BOM: Explique o PORQUÊ, não o QUÊ
// Use backoff exponencial para evitar sobrecarregar a API durante interrupções
const atraso = Math.min(1000 * Math.pow(2, contagemTentativas), 30000)

// Mutação intencional aqui por desempenho com arrays grandes
itens.push(novoItem)

// FAIL: RUIM: Afirmando o óbvio
// Incrementar contador em 1
contador++

// Definir nome como nome do usuário
nome = usuario.nome

JSDoc para APIs Públicas

/**
 * Pesquisa mercados usando similaridade semântica.
 *
 * @param query - Consulta de pesquisa em linguagem natural
 * @param limit - Número máximo de resultados (padrão: 10)
 * @returns Array de mercados ordenados por pontuação de similaridade
 * @throws {Error} Se a API OpenAI falhar ou Redis estiver indisponível
 *
 * @example
 * ```typescript
 * const resultados = await pesquisarMercados('eleição', 5)
 * console.log(resultados[0].nome) // "Trump vs Biden"
 * ```
 */
export async function pesquisarMercados(
  query: string,
  limit: number = 10
): Promise<Mercado[]> {
  // Implementação
}

Melhores Práticas de Desempenho

Memorização

import { useMemo, useCallback } from 'react'

// PASS: BOM: Memorizar cálculos caros
// Copiar antes de ordenar - Array.prototype.sort modifica no local
const mercadosOrdenados = useMemo(() => {
  return [...mercados].sort((a, b) => b.volume - a.volume)
}, [mercados])

// PASS: BOM: Memorizar callbacks
const handleBusca = useCallback((query: string) => {
  setConsultaPesquisa(query)
}, [])

Carregamento Preguiçoso (Lazy Loading)

import { lazy, Suspense } from 'react'

// PASS: BOM: Carregar componentes pesados preguiçosamente
const GraficoPesado = lazy(() => import('./GraficoPesado'))

export function Dashboard() {
  return (
    <Suspense fallback={<Spinner />}>
      <GraficoPesado />
    </Suspense>
  )
}

Consultas ao Banco de Dados

// PASS: BOM: Selecionar apenas as colunas necessárias
const { data } = await supabase
  .from('mercados')
  .select('id, nome, status')
  .limit(10)

// FAIL: RUIM: Selecionar tudo
const { data } = await supabase
  .from('mercados')
  .select('*')

Padrões de Teste

Estrutura de Teste (Padrão AAA)

teste('calcula similaridade corretamente', () => {
  // Arrange (Organizar)
  const vetor1 = [1, 0, 0]
  const vetor2 = [0, 1, 0]

  // Act (Agir)
  const similaridade = calcularSimilaridadeCosseno(vetor1, vetor2)

  // Assert (Afirmar)
  expect(similaridade).toBe(0)
})

Nomenclatura de Testes

// PASS: BOM: Nomes de teste descritivos
teste('retorna array vazio quando nenhum mercado corresponde à consulta', () => { })
teste('lança erro quando a chave da API OpenAI está faltando', () => { })
teste('recorre à pesquisa de substring quando Redis está indisponível', () => { })

// FAIL: RUIM: Nomes de teste vagos
teste('funciona', () => { })
teste('testar pesquisa', () => { })

Detecção de Code Smells

Fique atento a esses anti-padrões:

1. Funções Longas

// FAIL: RUIM: Função > 50 linhas
function processarDadosMercado() {
  // 100 linhas de código
}

// PASS: BOM: Dividir em funções menores
function processarDadosMercado() {
  const validados = validarDados()
  const transformados = transformarDados(validados)
  return salvarDados(transformados)
}

2. Aninhamento Profundo

// FAIL: RUIM: 5+ níveis de aninhamento
if (usuario) {
  if (usuario.isAdmin) {
    if (mercado) {
      if (mercado.isAtivo) {
        if (temPermissao) {
          // Fazer algo
        }
      }
    }
  }
}

// PASS: BOM: Retornos antecipados
if (!usuario) return
if (!usuario.isAdmin) return
if (!mercado) return
if (!mercado.isAtivo) return
if (!temPermissao) return

// Fazer algo

3. Números Mágicos

// FAIL: RUIM: Números inexplicados
if (contagemTentativas > 3) { }
setTimeout(callback, 500)

// PASS: BOM: Constantes nomeadas
const MAX_TENTATIVAS = 3
const ATRASO_DEBOUNCE_MS = 500

if (contagemTentativas > MAX_TENTATIVAS) { }
setTimeout(callback, ATRASO_DEBOUNCE_MS)

Lembre-se: Qualidade de código não é negociável. Código claro e sustentável permite desenvolvimento rápido e refatoração confiante.