YYY920/video-ops-skill

Escrevendo Componentes React

Estamos usando React moderno (19+) e seguindo as melhores práticas comuns focadas em clareza, correção e manutenibilidade.

Estrutura e Estilo de Componentes

• PREFIRA componentes pequenos e focados, com uma única responsabilidade
• PREFIRA componentes function nomeados em vez de arrow functions
  • Exceção: callbacks anônimos, render props inline e closures
• PREFIRA tipos de retorno explícitos e tipagem de props (TypeScript) quando aplicável
• Mantenha os componentes planos e legíveis; evite JSX profundamente aninhado
• Agrupe lógica relacionada (manipuladores de eventos, valores derivados, auxiliares)

Gerenciamento de Estado

• EVITE useEffect()
  • Veja o guia "Você Provavelmente Não Precisa de um Efeito" para orientação detalhada
  • PREFIRA derivar valores durante a renderização em vez de sincronizar estado
  • Busque dados via TanStack Query (@tanstack/react-query)
• EVITE uso desnecessário de useState() ou useReducer()
  • Derive estado de props ou de outro estado quando possível
  • Localize o estado no componente mais baixo possível
• NÃO espelhe props em estado a menos que absolutamente necessário
• Prefira componentes controlados em vez de sincronizar estado não controlado

Renderização e Derivação

• PREFIRA calcular valores derivados inline ou através de funções auxiliares
• Use useMemo() com moderação e apenas para problemas de desempenho comprovados
• EVITE otimização prematura
• Mantenha a lógica de renderização determinística e livre de efeitos colaterais

Manipulação de Eventos

• EVITE manipuladores de eventos inline em JSX

  • PREFIRA:

    function handleClick() {
      // ...
    }
    
    <button onClick={handleClick} />;
    

  • Em vez de:

    <button
      onClick={() => {
        /* ... */
      }}
    />
    

• Nomeie manipuladores claramente (handleSubmit, handleChange, handleClose)

• Mantenha manipuladores pequenos; extraia lógica complexa em auxiliares

Efeitos, Dados e Efeitos Colaterais

• EVITE efeitos para:
  • Estado derivado
  • Transformações de dados
  • Lógica baseada em eventos que pode viver em manipuladores
• Se efeitos colaterais forem inevitáveis, mantenha-os mínimos, isolados e bem documentados
• Prefira abstrações de nível de framework ou externas (roteadores, bibliotecas de dados) em vez de efeitos brutos

Props e Composição

• PREFIRA composição em vez de configuração
• EVITE props booleanas excessivas; prefira APIs expressivas
• Use children intencionalmente e documente a estrutura esperada
• Mantenha nomes de props semânticos e previsíveis

Desempenho e Estabilidade

• PREFIRA referências estáveis apenas quando necessário (não por padrão)
• EVITE memoização desnecessária (memo, useCallback) a menos que absolutamente necessário
• Mantenha chaves estáveis e significativas ao renderizar listas

Princípios Gerais

• Escreva código para humanos primeiro, compiladores depois
• Prefira explicitude em vez de esperteza
• Otimize para legibilidade e manutenção a longo prazo
• Se um padrão parecer complexo, reconsidere o limite do componente