Melhores Práticas para Revisão de Código Flutter/Dart

Checklist abrangente e independente de bibliotecas para revisar aplicações Flutter/Dart. Estes princípios se aplicam independentemente da solução de gerenciamento de estado, biblioteca de roteamento ou framework de DI utilizada.

1. Saúde Geral do Projeto

• O projeto segue uma estrutura de pastas consistente (orientada a funcionalidade ou a camadas)
• Separação adequada de responsabilidades: UI, lógica de negócios, camadas de dados
• Sem lógica de negócios em widgets; widgets são puramente de apresentação
• pubspec.yaml está limpo — sem dependências não utilizadas, versões fixadas apropriadamente
• analysis_options.yaml inclui um conjunto estrito de lints com configurações de analisador estritas habilitadas
• Sem instruções print() em código de produção — use dart:developer log() ou um pacote de logging
• Arquivos gerados (.g.dart, .freezed.dart, .gr.dart) estão atualizados ou em .gitignore
• Código específico da plataforma isolado por trás de abstrações

2. Armadilhas da Linguagem Dart

• dynamic implícito: Anotações de tipo ausentes levando a dynamic — habilite strict-casts, strict-inference, strict-raw-types
• Uso indevido de segurança contra nulos: Excesso de ! (operador bang) em vez de verificações de nulo adequadas ou correspondência de padrões do Dart 3 (if (value case var v?))
• Falhas na promoção de tipo: Usando this.field onde a promoção de variável local funcionaria
• Capturando de forma muito ampla: catch (e) sem cláusula on; sempre especifique os tipos de exceção
• Capturando Error: Subtipos de Error indicam bugs e não devem ser capturados
• async não utilizado: Funções marcadas como async que nunca await — sobrecarga desnecessária
• Uso excessivo de late: late usado onde inicialização anulável ou de construtor seria mais segura; adia erros para o tempo de execução
• Concatenação de strings em loops: Use StringBuffer em vez de + para construção iterativa de strings
• Estado mutável em contextos const: Campos em classes de construtor const não devem ser mutáveis
• Ignorando valores de retorno de Future: Use await ou chame explicitamente unawaited() para sinalizar a intenção
• var onde final funciona: Prefira final para locais e const para constantes em tempo de compilação
• Imports relativos: Use imports package: para consistência
• Coleções mutáveis expostas: APIs públicas devem retornar visualizações não modificáveis, não List/Map brutos
• Falta de correspondência de padrões do Dart 3: Prefira expressões switch e if-case em vez de verificações verbosas de is e casting manual
• Classes descartáveis para múltiplos retornos: Use registros do Dart 3 (String, int) em vez de DTOs de uso único
• print() em código de produção: Use dart:developer log() ou o pacote de logging do projeto; print() não tem níveis de log e não pode ser filtrado

3. Melhores Práticas de Widget

Decomposição de Widget:

• Nenhum widget único com um método build() excedendo ~80-100 linhas
• Widgets divididos por encapsulamento E por como eles mudam (limites de reconstrução)
• Métodos auxiliares privados de _build*() que retornam widgets são extraídos para classes de widget separadas (permite reutilização de elementos, propagação de const e otimizações do framework)
• Widgets Stateless preferidos sobre Stateful onde nenhum estado local mutável é necessário
• Widgets extraídos estão em arquivos separados quando reutilizáveis

Uso de const:

• Construtores const usados sempre que possível — evita reconstruções desnecessárias
• Literais const para coleções que não mudam (const [], const {})
• O construtor é declarado const quando todos os campos são final

Uso de Key:

• ValueKey usado em listas/grades para preservar o estado entre reordenações
• GlobalKey usado com moderação — apenas quando o acesso ao estado através da árvore é realmente necessário
• UniqueKey evitado em build() — força a reconstrução a cada frame
• ObjectKey usado quando a identidade é baseada em um objeto de dados em vez de um único valor

Tematização e sistema de design:

• Cores vêm de Theme.of(context).colorScheme — sem Colors.red codificados ou valores hexadecimais
• Estilos de texto vêm de Theme.of(context).textTheme — sem TextStyle inline com tamanhos de fonte brutos
• Compatibilidade com modo escuro verificada — sem suposições sobre fundo claro
• Espaçamento e dimensionamento usam tokens de design ou constantes consistentes, não números mágicos

Complexidade do método build:

• Sem chamadas de rede, I/O de arquivo ou computação pesada em build()
• Sem trabalho de Future.then() ou async em build()
• Sem criação de assinatura (.listen()) em build()

…