Padrões de Código e Melhores Práticas

Convenções de codificação de base aplicáveis a todos os projetos.

Essa habilidade é 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 um guia completo de habilidades.

Quando Ativar

• Iniciando um novo projeto ou módulo
• Revisando código para qualidade e manutenibilidade
• Refatorando código existente para seguir convenções
• Aplicando consistência de nomenclatura, formatação ou estrutura
• Configurando regras de linting, formatação ou verificação de tipos
• Integrando novos colaboradores às convenções de codificação

Limites de Escopo

Ative esta habilidade para:

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

Não use esta habilidade como fonte primária para:

• composição de React, hooks ou padrões de renderização
• arquitetura de backend, design de API ou camadas de banco de dados
• orientação de framework específica de domínio quando uma habilidade ECC mais restrita já existe

Princípios de Qualidade de Código

1. Legibilidade em Primeiro Lugar

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

2. KISS (Mantenha Simples, Estúpido)

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

3. DRY (Não Se Repita)

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

4. YAGNI (Você Não Vai Precisar Disso)

• Não crie funcionalidades antes que sejam necessárias
• Evite generalidade especulativa
• Adicione complexidade apenas quando necessário
• Comece simples, refatore quando necessário

Padrões TypeScript/JavaScript

Nomenclatura de Variáveis

// PASS: GOOD: Descriptive names
const marketSearchQuery = 'election'
const isUserAuthenticated = true
const totalRevenue = 1000

// FAIL: BAD: Unclear names
const q = 'election'
const flag = true
const x = 1000

Nomenclatura de Funções

// PASS: GOOD: Verb-noun pattern
async function fetchMarketData(marketId: string) { }
function calculateSimilarity(a: number[], b: number[]) { }
function isValidEmail(email: string): boolean { }

// FAIL: BAD: Unclear or noun-only
async function market(id: string) { }
function similarity(a, b) { }
function email(e) { }

Padrão de Imutabilidade (CRÍTICO)

// PASS: ALWAYS use spread operator
const updatedUser = {
  ...user,
  name: 'New Name'
}

const updatedArray = [...items, newItem]

// FAIL: NEVER mutate directly
user.name = 'New Name'  // BAD
items.push(newItem)     // BAD

Tratamento de Erros

// PASS: GOOD: Comprehensive error handling
async function fetchData(url: string) {
  try {
    const response = await fetch(url)

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

    return await response.json()
  } catch (error) {
    console.error('Fetch failed:', error)
    throw new Error('Failed to fetch data')
  }
}

// FAIL: BAD: No error handling
async function fetchData(url) {
  const response = await fetch(url)
  return response.json()
}

Melhores Práticas Async/Await

// PASS: GOOD: Parallel execution when possible
const [users, markets, stats] = await Promise.all([
  fetchUsers(),
  fetchMarkets(),
  fetchStats()
])

// FAIL: BAD: Sequential when unnecessary
const users = await fetchUsers()
const markets = await fetchMarkets()
const stats = await fetchStats()

Segurança de Tipos

// PASS: GOOD: Proper types
interface Market {
  id: string
  name: string
  status: 'active' | 'resolved' | 'closed'
  created_at: Date
}

function getMarket(id: string): Promise<Market> {
  // Implementation
}

// FAIL: BAD: Using 'any'
function getMarket(id: any): Promise<any> {
  // Implementation
}

Melhores Práticas de React

Estrutura de Componentes

// APROVADO: 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 (

…