code-comments · git:20260925.971e044 · 2026-09-25 · sha256 ec8e17d0b5b2f5e6

code-comments git:20260925.971e044A

Immutable. This exact content never changes and is served at /api/v1/blob/ec8e17d0b5b2f5e6.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_lf6zfb5rbguhqzni/ec8e17d0b5b2f5e66a24a7c4bc17fe6c7efb76d8b01ce23a6bad129ed7700ff9.json

Then /plugin install code-comments@markdownregistry-lf6zfb5rbguhqzni in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: code-comments
description: >
  Define quando um comentário é permitido e quando é ruído em código TypeScript e
  NestJS. Elimina comentários óbvios que repetem o código, cabeçalhos de seção, imports
  explicados e narração de edições passadas. Estabelece o teste das três perguntas e o
  passe de poda obrigatório antes de fechar a tarefa. Use ao criar, editar ou revisar
  arquivos .ts, .json ou YAML.
---

# Comentários em código-fonte

> **Manutenção desta skill**
>
> Atualize este documento sempre que mudar **qualquer regra descrita aqui**. O critério não
> é *qual* regra — é a natureza da mudança: a política de comentários do projeto mudou →
> atualize; refator técnico que preserva a política descrita → não toque.

Esta regra aplica-se a todo o repositório, em qualquer arquivo de código-fonte TypeScript
(`*.ts`), configurações (`*.json`, `*.yaml`) e scripts.

## O comentário é exceção, não hábito

Comentários devem ser evitados, a não ser que sejam estritamente necessários para explicar
decisão não intuitiva, restrição técnica externa, tradeoff ou contexto inacessível apenas pela
leitura do código. O código deve ser autoexplicativo através de nomes expressivos, tipos estritos
e abstrações coesas.

Correto — explica contexto externo e restrição que o código não expressa sozinho:

```typescript
/*
 * O SDK do ACP exige envio do cwd normalizado em formato POSIX para evitar falha
 * na resolução de caminhos em plataformas Windows e ambientes conteinerizados.
 */
const normalizedCwd = cwd.replace(/\\/g, '/');
```

Evite — apenas repete a mecânica visível do código:

```typescript
// substitui barras invertidas por barras normais
const normalizedCwd = cwd.replace(/\\/g, '/');
```

O nome do símbolo, a assinatura do método e os tipos do TypeScript são o canal primário de
explicação. Antes de recorrer a um comentário, elimine a ambiguidade: renomeie a variável,
extraia constantes para números ou strings mágicas, reforce os tipos ou extraia métodos
privados na classe.

## Teste das três perguntas

Submeta cada comentário pretendido às três perguntas abaixo antes de escrevê-lo. Se responder
"não" a qualquer uma, **o comentário não entra**:

1. **Ele diz algo que o código não diz?** Se a informação pode ser deduzida lendo os tipos, o
   nome do método ou as instruções seguintes, é ruído.
2. **Um leitor competente tentaria a alternativa que ele descarta?** Comentários que explicam
   "por que não fizemos X" só fazem sentido se X for uma abordagem atraente e comum que falha
   por uma razão não evidente.
3. **Ele continuará verdadeiro após a próxima refatoração?** Comentários que descrevem a ordem
   dos passos, nomes de variáveis ou fluxos internos viram mentiras assim que o código é
   refatorado. Apenas decisões duráveis sobrevivem.

## Catálogo de comentários proibidos

Os casos a seguir exemplificam violações que devem ser ativamente eliminadas:

**Repetir a assinatura, classe ou nome do método:**

```typescript
// busca o agente pelo id
async findAgentById(id: string): Promise<AgentEntity> {
```

**Comentar imports ou injeções de dependência no NestJS:**

```typescript
// importa o caso de uso de conexão
import { ConnectAgentUseCase } from './connect-agent.use-case.ts';

// injeta a porta do Discord
@Inject(IDiscordPort)
private readonly discordPort: IDiscordPort,
```

**Cabeçalhos de seção, divisores ou separadores visuais:**

```typescript
// ==========================================
// Handlers de Eventos
// ==========================================
// Métodos Privados
```

**Nomear o passo trivial dentro de um método:**

```typescript
// valida se o payload existe
if (!payload) throw new BadRequestException();

// chama o caso de uso
await this.useCase.execute(payload);
```

**JSDoc que apenas duplica informações de tipagem do TypeScript:**

```typescript
/**
 * @param sessionId - O ID da sessão
 * @returns Retorna a sessão encontrada
 */
```

**Comentários de TODO ou FIXME vagos e sem contexto:**
Marcadores como `// TODO: ajustar depois` ou `// FIXME: erro aqui` sem descrição do critério
de conclusão nem link para issue são proibidos. Débitos e pendências pertencem ao backlog ou
à descrição de tarefas, não ao código-fonte.

## O comentário descreve o código de hoje

O leitor do código consulta o arquivo no presente, sem interesse no histórico de revisões que
deram origem àquela linha.

- **Não comente a edição**: Explicações sobre abordagens anteriores descartadas, bugs antigos
  corrigidos ou justificativas de migração pertencem à mensagem de commit e ao Pull Request.
- **Escreva a partir do resultado final**: Descreva a restrição como uma característica do
  código atual, e não como uma transição ("passou a ser", "deixou de usar").

## Passe de poda antes de fechar a tarefa

Antes de finalizar qualquer tarefa que inclua ou altere código:

1. Inspecione no diff (`git diff`) todas as linhas de comentário adicionadas.
2. Aplique o teste das três perguntas a cada uma delas.
3. Apague sem hesitar qualquer comentário redundante, explicativo de sintaxe ou narração de
   edição recente.