Skip to content
EBDbe

adr-0020-padrao-de-comentarios-intencionais-no-codigo

Decisão

Section titled “Decisão”

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

1. Princípio Geral

Section titled “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

Section titled “2. Formato Oficial”

Comentários locais (padrão principal)

Section titled “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

Section titled “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)

Section titled “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

Section titled “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

Section titled “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

Section titled “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