Spec — Code Comments

Facet *ode*do Koder Design.

Codifica formalmente a regra global do CLAUDE.md ("default to no comments") como spec auditável + estende com formato per-lang, doc styles, TODO conventions e anti-patterns.

Filosofia: WHYnotWHAT

*efault* não escrever comentário. Identificadores bem nomeados (per code/naming.kmd) + funções curtas (per code/functions.kmd) *ão*a documentação primária do que o código faz.

*screver comentário só quando*

• Escondese um *HY*nãoóbvio (constraint de negócio, invariante

  sutil, workaround por bug específico, comportamento que surpreende)

• O comportamento depende de algo *ora do arquivo*(spec externa,

  protocolo de terceiros, RFC, ticket de incidente)

• A escolha entre alternativas igualmente válidas precisa de

  justificativa pra evitar refactor inútil futuro

*ão escrever comentário quando*

• Apenas repete o nome do identificador (# increment counter em

  cima de counter += 1)

• Descreve o WHAT que já é óbvio do código
• Referencia o "task atual""este fix""caller X" — isso pertence

  à PR description, não ao código (commit message + git blame preservam a referência sem rotação)

• Marca código removido (# was: foo()) — git history tem isso

Exemplos

# ❌ Comenta o WHAT óbvio
# increment retry counter
retries += 1

# ✅ Comenta o WHY não-óbvio
# OAuth2 server occasionally returns 502 mid-handshake (vendor bug
# tracked in #4471); retry up to MAX_RETRIES with backoff before
# surfacing failure
retries += 1

# ❌ Referencia task atual (rotaciona)
# Added for the new login flow PR-#1234
def authenticate(token)

# ✅ Pertence ao PR/commit, não ao código
def authenticate(token)

Estilo léxico per-language

*rincípio* usar o formato *diomático*da linguagem; não forçar uniformidade total que viola o uso esperado pelo IDE/linter.

Doc comments

R1 — Quando obrigatório

• *oda funçãométodoclasse pública*(exportada do módulo)
• *oda constant pública não-trivial*(não óbvia pelo nome)
• *odo módulo/package*(docstring no topo)

R2 — Quando opcional

• Funções privadas curtas (≤10 linhas) com nome auto-explicativo
• Test functions (nome test_ ou it_should_ é a doc)

R3 — Formato

Mínimo: * linha de resumo* Quando relevante: * linha em branco + detalhes*(parâmetros, retorno, raises, exemplos).

def hash_password(password: str) -> str:
    """Hash a password with Argon2id."""

def hash_password(password: str, *, time_cost: int = 3) -> str:
    """Hash a password with Argon2id.

    Time cost defaults to 3 (OWASP 2024 recommendation). Use higher
    values for high-security contexts; benchmark target: ~50ms on
    modern CPU.

    Args:
      password: Plaintext password (max 72 bytes effective).
      time_cost: Argon2 t parameter; 3 ≤ t ≤ 10.

    Returns:
      PHC-format hash string (`$argon2id$v=19$...`).

    Raises:
      ValueError: If password is empty or time_cost out of range.
    """

R4 — Koda specific (#: triple-line)

Ver code/languages/koda-style.kmd § Doc comments. Resumo:

#: Compute SHA-256 hash of a string.
#:
#: Returns 64-char lowercase hex. Raises EncodingError on
#: invalid UTF-8.
def sha256(s)
  ...
end

TODO / FIXME / HACK / XXX / NOTE / WARN

R5 — Formato canônico

# TODO(@handle, ticket): description
# FIXME(@handle, ticket): description
# HACK(@handle, ticket): description — explanation of why
# XXX(@handle): something dangerous; needs careful review
# NOTE: something readers should know but isn't actionable
# WARN: behavior that surprises; non-obvious side effect

R6 — Quando usar cada um

R7 — Regras

• TODOFIXMEHACK *evem*ter (@handle, ticket) — autor + ticket

  de tracking

• Linter falha se TODO/FIXME sem ticket após 30 dias
• HACK exige *xplicação do porquê*após : (não pode ser só

  # HACK: fix later)

• XXX não exige ticket mas exige revisão code-review
• Markers em *nglês*(mesmo em comentário pt-BR raro — markers

  são vocabulário fechado universal)

R8 — Heisenbug workarounds

Caso especial: diagnóstico que "acidentalmente conserta" um bug pode ser shipado como workaround permanente, *as exige*

• Comentário explícito explicando que é workaround
• Ticket de followup pra rootcause investigation
• Marker HACK ou XXX

(Padrão registrado em memory feedback_heisenbug_workaround_pattern.)

Commented-out code

*roibido* Delete + git history. Linter falha se ≥5 linhas consecutivas comentadas com sintaxe que casa com a linguagem.

# ❌
def foo():
    bar()
    # baz()
    # qux()
    # frob()
    return bar.result()

# ✅
def foo():
    bar()
    return bar.result()
# git blame mostra o que foi removido

Exceção rara: bloco de exemplo/template em README ou doc comment (aceito porque o # está dentro de docstring/markdown).

Section headers

Quando arquivo tem ≥200 linhas e seções lógicas distintas, usar section headers:

# ============================================================
# Public API
# ============================================================

def authenticate(...): ...
def logout(...): ...

# ============================================================
# Internal helpers
# ============================================================

def _hash(...): ...

Não obrigatório; não adicionar em arquivos curtos onde o file outline do IDE já dá a estrutura.

License header

R9 — Política Koder

Default: *ão exigir*license header em todo arquivo. Razões:

• LICENSE no root do repo é canônica
• Header em todo arquivo polui git diff e onboarding
• Tooling moderno (SBOM, REUSE) lê do LICENSE direto

*xceção* arquivos publicados como SDK público pra terceiros (em `engines/sdk