Skip to main content

ADR-0020 — Padrão de Comentários Intencionais no Código

Status​

Aprovado

Contexto​

O projeto EBDbe evolui com base em princípios de arquitetura controlada, governança via ADR e uso assistido de Inteligência Artificial.

Com o crescimento do código (Flutter + TypeScript), observou-se a necessidade de:

  • Melhorar a legibilidade do código
  • Tornar a intenção de blocos mais clara
  • Facilitar onboarding futuro
  • Permitir geração de documentação arquitetural
  • Evitar poluição visual e comentários redundantes

Ao mesmo tempo, comentários excessivos ou explicações óbvias reduzem a qualidade do código e dificultam manutenção.

Torna-se necessário definir um padrão oficial de comentários que seja:

  • Minimalista
  • Intencional
  • Arquitetural
  • Compatível com geração futura de documentação
  • Adequado ao uso de IA assistiva (Cursor)

Decisão​

Fica estabelecido o padrão oficial de comentários do projeto EBDbe.

1. Princípio Geral​

Comentários devem explicar intenção, nunca mecânica.

Deve-se comentar:

  • Aplicação de regra de negócio
  • Transformações relevantes
  • Validações
  • Integrações externas
  • Decisões arquiteturais não triviais

Não se deve comentar:

  • Código autoexplicativo
  • Sintaxe óbvia
  • Operações triviais

2. Formato Oficial​

Comentários locais (padrão principal)​

Uso de comentário de uma única linha.

TypeScript:

// Normaliza e-mail antes de persistir
// Aplica regra de permissão do usuário

Dart:

// Normaliza e-mail antes de persistir
// Aplica regra de permissão do usuário

Regras:

  • Máximo de 1 comentário por bloco lógico
  • Texto curto e descritivo
  • Sem redundância
  • Sem explicar "como", apenas "o que"

3. Documentação de Elementos Públicos​

Para classes e funções exportadas, deve-se utilizar bloco compacto.

TypeScript:

/**
 * Context: Auth
 * Responsibility: Gerenciar autenticação de usuários
 */

Dart:

/// Context: Login
/// Responsibility: Controlar fluxo de autenticação

4. Integração com IA (Cursor)​

A IA pode:

  • Inserir comentários seguindo este padrão
  • Sugerir melhoria de clareza
  • Adicionar comentários apenas onde houver regra de negócio

A IA não deve:

  • Supercomentar
  • Inserir explicações óbvias
  • Alterar lógica ao adicionar comentários

Em caso de dúvida, a regra é: não comentar.

5. Compatibilidade com Documentação​

Este padrão permite futura extração automatizada para:

  • Documentação arquitetural
  • Organização por contexto
  • Geração de conteúdo no Docusaurus

A adoção de tags estruturadas (ex.: Context, Responsibility) é opcional, porém recomendada em elementos públicos.

6. Frequência Recomendada​

Diretriz prática:

  • No máximo 1 comentário a cada 15–20 linhas
  • Apenas quando houver lógica relevante
  • Código limpo é prioritário sobre documentação excessiva

Consequências​

  • O código torna-se mais legível e sustentável
  • Reduz-se ruído visual
  • Facilita onboarding técnico
  • Mantém alinhamento com princípios arquiteturais
  • Evita documentação desnecessária
  • A IA passa a operar sob diretriz formal registrada
  • Este ADR formaliza o padrão oficial de comentários do projeto
Last updated on