Plano de Verificação de Comentários — ADR-0020
Referência: ADR-0020 — Padrão de Comentários Intencionais no Código.
Objetivo: percorrer todo o código da solução (frontend Dart, backend TypeScript) e alinhar comentários ao padrão do ADR-0020 (intenção, não mecânica; minimalista; máx. ~1 comentário a cada 15–20 linhas; elementos públicos com bloco Context/Responsibility quando fizer sentido).
Critérios de verificação (checklist por arquivo)
Para cada arquivo, aplicar:
| Critério | Ação |
|---|---|
| Comentar intenção | Onde houver regra de negócio, validação, transformação relevante ou integração externa: 1 linha // O que está sendo feito (intenção) ou equivalente. |
| Não comentar óbvio | Remover comentários que explicam sintaxe, “como” o código faz, ou operações triviais. |
| Frequência | Máximo ~1 comentário por bloco lógico; no máximo ~1 a cada 15–20 linhas onde há lógica relevante. |
| Elementos públicos | Classes/funções exportadas (ou públicas em Dart): considerar bloco compacto com Context e Responsibility (opcional mas recomendado). |
| Sem supercomentar | Em dúvida: não comentar. |
Ordem de execução recomendada
Ordem por camada (de dentro para fora), para manter consistência primeiro no núcleo.
Fase 1 — Backend (TypeScript)
| # | Camada / Diretório | Escopo | Prioridade |
|---|---|---|---|
| 1 | backend/functions/src/domain/ | Entidades, value objects, tipos. Foco: documentação de tipos/entidades públicas e comentários de intenção em regras de domínio. | Alta |
| 2 | backend/functions/src/domain/ports/ | Interfaces (repositórios, serviços). Foco: bloco /** Context / Responsibility */ nas interfaces exportadas. | Alta |
| 3 | backend/functions/src/application/use-cases/ | Casos de uso. Foco: intenção de passos (validações, orquestração, regras de negócio). | Alta |
| 4 | backend/functions/src/application/services/ | Serviços de aplicação (ex.: role-catalog-service). Foco: intenção de métodos públicos e blocos lógicos relevantes. | Alta |
| 5 | backend/functions/src/infrastructure/repositories/ | Implementações Firestore e outros adaptadores. Foco: mapeamentos, normalizações, integração externa. | Média |
| 6 | backend/functions/src/infrastructure/services/ | Serviços de infra (ex.: resend-email). Foco: integração externa e contratos. | Média |
| 7 | backend/functions/src/interfaces/http/ | Controllers HTTP. Foco: responsabilidade do endpoint e validação de entrada quando relevante. | Média |
| 8 | backend/functions/src/shared/ | Bootstrap, debug-context, etc. Foco: intenção de funções/objetos compartilhados. | Baixa |
| 9 | backend/functions/src/scripts/ | Scripts de migração/one-off. Foco: intenção do script e passos principais. | Baixa |
Fase 2 — Frontend (Dart)
| # | Camada / Diretório | Escopo | Prioridade |
|---|---|---|---|
| 10 | frontend/lib/domain/ | Entidades, erros, repositórios (interfaces). Foco: documentação de classes públicas e comentários onde houver invariantes ou regras. | Alta |
| 11 | frontend/lib/application/ | Use cases, serviços (ex.: user_profile_service, role_catalog_service). Foco: intenção de métodos públicos e fluxos. | Alta |
| 12 | frontend/lib/infrastructure/ | Implementações (auth, profile, etc.). Foco: mapeamentos, chamadas HTTP, normalização de dados. | Alta |
| 13 | frontend/lib/core/ | DI, config, theme. Foco: responsabilidade de módulos e configurações não óbvias. | Média |
| 14 | frontend/lib/presentation/pages/ | Páginas (home, login, register). Foco: intenção de blocos de UI/estado, não descrição de widget. | Média |
| 15 | frontend/lib/presentation/modules/ | Módulos (ex.: profile_dialog). Foco: intenção de fluxos e handlers, não óbvio. | Média |
| 16 | frontend/lib/presentation/widgets/ | Widgets reutilizáveis. Foco: responsabilidade do widget quando não for óbvia. | Média |
| 17 | frontend/lib/shared/ | Debug, image, widgets compartilhados. Foco: intenção de utilitários e serviços compartilhados. | Baixa |
Forma de registro (opcional)
- Por fase: anotar arquivos já revisados (ex.: lista em um checklist ou “ADR-0020 verificado” no cabeçaligo do arquivo, se o projeto adotar).
- Problemas encontrados: comentários redundantes removidos; comentários de intenção adicionados (resumo por pasta).
- Exceções: trechos deixados sem comentário por serem autoexplicativos; trechos com comentário excepcional (ex.: workaround) com uma linha justificando.
Estimativa e ritmo
- Backend: ~88 arquivos .ts; priorizar domain → application → infrastructure → interfaces → shared/scripts.
- Frontend: ~66 arquivos .dart; priorizar domain → application → infrastructure → core → presentation → shared.
- Sugestão: 1–2 sessões por fase (ex.: Fase 1 em 1–2 sessões, Fase 2 em 1–2 sessões), revisando por pasta e aplicando o checklist acima.
Resumo
- Usar ADR-0020 como referência única para “comentar o quê” e “como”.
- Verificar em ordem de camada (domain → application → infrastructure → interfaces/presentation).
- Em cada arquivo: adicionar comentários de intenção onde houver RN/validação/integração; remover comentários óbvios ou de mecânica; considerar bloco Context/Responsibility em elementos públicos.
- Em dúvida: não comentar.
- Opcional: manter registro por pasta/fase para acompanhamento e futura extração para documentação (conforme ADR-0020 §5).