---
title: "Comentários Resíduo de Prompt"
type: "ai-smell"
slug: "prompt-residue-comments"
url: "http://localhost:3000/pt-br/ai-smells/prompt-residue-comments.md"
category: "Clareza"
description: "Comentários que são artefatos da conversa de geração — prompts reformulados, narração passo a passo, comentários de bate-papo e elisões com placeholders como `// ... resto do código aqui` — versionados no código-fonte em vez de documentação real."
---
# Comentários Resíduo de Prompt

> Comentários que são artefatos da conversa de geração — prompts reformulados, narração passo a passo, comentários de bate-papo e elisões com placeholders como `// ... resto do código aqui` — versionados no código-fonte em vez de documentação real.

## Signs and Symptoms

Um revisor identifica Comentários Resíduo de Prompt quando os comentários documentam a _conversa que produziu o código_ em vez do próprio código. Quatro indícios, muitas vezes coocorrendo:

* **Prompt reformulado** — um comentário que parafraseia o pedido literalmente (`// Função para somar dois números`) acima de uma função literalmente chamada `add`.
* **Narração de passos** — narração linha a linha de operações óbvias (`// Passo 1: percorrer o array`, `// incrementa i em 1` acima de `i++`).
* **Comentários de bate-papo** — observações em segunda pessoa, no presente, dirigidas a _você_, o solicitante (`// Conforme solicitado, aqui está o handler atualizado`, `// Claro! Aqui está a correção`, `// Nota: substitua pela sua chave de API real`).
* **Resíduo de elisão / placeholder** — `// ... resto do código aqui`, `// mantenha sua lógica existente`, `// seu código aqui`, `// TODO: implementar tratamento de erros` deixados no código-fonte versionado.

```ts
// Função para somar dois números e retornar o resultado   <- reformula o prompt
function add(a: number, b: number): number {
  // Passo 1: somar os dois números                          <- narra o óbvio
  const sum = a + b;
  return sum; // retorna a soma
}

// Conforme solicitado, aqui está o handler atualizado        <- comentário de bate-papo para "você"
export async function handler(req: Req, res: Res) {
  // ... mantenha sua lógica de validação existente aqui ...   <- elisão: código real descartado
  // TODO: implementar tratamento de erros                     <- placeholder entregue como está
  const user = await db.users.find(req.params.id);
  res.json(user);
}

```

A linha de elisão é a perigosa: ela lê como documentação, mas na verdade é uma instrução para um humano colar código que o modelo omitiu — aplique o bloco literalmente e a validação existente desaparece silenciosamente. A OX Security encontrou "Comentários por Toda Parte" em **90–100%** do código gerado por IA em seu estudo de mais de 300 repositórios, descrevendo-os como marcadores que "parecem úteis, mas principalmente apoiam a própria IA, entulhando os repositórios".

## Reasons for the Problem

**Por que os modelos os emitem**

* **Mimetismo de próximo token dos corpora de tutorial.** A mistura de treinamento está saturada de posts de blog, respostas do StackOverflow e documentação onde cada linha é explicada para um aprendiz. O modelo reproduz esse registro didático — narração e intenção reformulada — porque é a continuação estatisticamente provável, não porque o repositório ao redor precisa dela.
* **Vazamento do registro de bate-papo / bajulação.** O RLHF ajusta os assistentes para serem explicativos e agradáveis no _canal de bate-papo_. Esse tom conversacional e em segunda pessoa vaza para o _canal de código_, produzindo comentários como "Conforme solicitado…" e "Nota: você deveria…" que não fazem sentido algum quando o código é destacado da conversa.
* **Raciocínio narrado como comentários.** Os modelos externalizam seu plano ("Passo 1… Passo 2…") como comentários inline — vazamento de cadeia de raciocínio congelado no arquivo.
* **Elisão é um recurso de bate-papo, mal aplicado.** Em uma resposta de bate-papo, `// ... resto inalterado ...` é uma forma educada de evitar reimprimir um arquivo. Quando essa resposta é colada ou aplicada automaticamente a um arquivo real, o recurso se torna resíduo literal — e perda literal de dados.
* **Sem contexto do repositório, então ele reformula o prompt.** Faltando o ticket, o domínio e o "porquê" real, o modelo não tem nada verdadeiro a dizer em um comentário, então recorre a parafrasear a única coisa que tem: o seu prompt. A OX caracteriza os comentários como "marcadores internos para navegar pelos limites de contexto… dependência de memória de curto prazo em vez de compreensão verdadeira".

**Por que isso prejudica**

* **Carga de revisão.** Cada linha de narração é ruído pelo qual um humano precisa passar. O enquadramento da OX: a IA "programa como um dev júnior" em velocidade de máquina, e a revisão humana "não consegue escalar para acompanhar a produção da IA" — comentários de resíduo tornam cada diff mais caro de revisar justamente quando há mais diffs.
* **Correção / perda de dados.** Placeholders de elisão (`// ...código existente...`) fazem com que código real seja descartado quando blocos são aplicados às cegas.
* **Apodrecimento de comentários.** Comentários de prompt reformulado duplicam a intenção do código em prosa; a prosa deriva conforme o código muda, deixando documentação ativamente enganosa — o clássico smell de _Comentários_\-como-desodorante de Fowler.
* **Incompletude oculta.** `// TODO: implementar tratamento de erros` é o modelo sinalizando que trabalhou no limite de sua competência; entregue como está, é lógica inacabada disfarçada de tarefa rastreada.
* **Indícios de segurança.** `// substitua pela sua chave de API real` normalmente fica ao lado de uma credencial placeholder codificada — o resíduo marca exatamente a linha com que um scanner (e um atacante) se importa.

## Treatment

**Táticas de prompting / geração**

* Restrinja o registro: _"Produza o arquivo completo. Nunca abrevie com `// ...`, `// resto do código` ou `// código existente`. Não narre passos — comente apenas o raciocínio não óbvio (o porquê). Sem comentários conversacionais; isto vai direto para um repositório."_
* Peça um **diff unificado** em vez de um trecho embrulhado em prosa, para que as omissões sejam explícitas e aplicáveis em vez de dissimuladas com um comentário de elisão.
* Exija que o modelo rode o formatador e sua configuração de lint (por exemplo, `no-warning-comments` com termos personalizados) e relate o resultado — fechar o loop de _"valide com o linter"_ captura resíduos de placeholder/TODO automaticamente.
* Adicione um portão de grep pré-commit / CI para marcadores de resíduo (`rest of the code`, `your code here`, `existing code`, `As requested`, `Step \d`) e trate os marcadores de elisão como um **bloqueador rígido**, já que eles muitas vezes significam que código foi silenciosamente descartado.

**A refatoração**

Apague comentários de bate-papo e narração de imediato. Onde um comentário apenas reformula _o que_ o código faz, esse é o sinal para tornar o código autodocumentado — aplique **Extrair Função** e **Renomear** para que o nome carregue a intenção, e então mantenha apenas comentários que expliquem um _porquê_ não óbvio (Fowler: _Remova comentários que são desodorante para nomes ruins_).

```ts
// antes — resíduo de prompt
// Crie uma função que valida um endereço de e-mail usando uma regex
function validateEmail(input) {
  // verifica se a entrada corresponde ao padrão de e-mail
  const re = /^[^@]+@[^@]+\.[^@]+$/;
  // retorna verdadeiro ou falso
  return re.test(input);
}

```

```ts
// depois — o nome carrega a intenção; o único comentário explica o porquê não óbvio
const EMAIL_RE = /^[^@]+@[^@]+\.[^@]+$/; // intencionalmente frouxo: só pegamos erros de digitação antes do envio, não RFC 5322
const isValidEmail = (input: string): boolean => EMAIL_RE.test(input);

```

Para resíduo de elisão, nunca aplique o bloco como está escrito — faça diff dele contra o arquivo atual e restaure o que o modelo descartou. Para `// TODO: implementar …`, ou finalize a lógica ou converta-a em uma issue rastreada e faça o build falhar no termo placeholder para que ele não possa ser entregue como está.

## Detected by

- **ESLint** `no-warning-comments` — Sinaliza TODO/FIXME/XXX e termos configuráveis personalizados — defina `terms` para capturar resíduos de placeholder como "your code here" ou "rest of the code" (https://eslint.org/docs/latest/rules/no-warning-comments)
- **SonarQube / SonarSource** `S125` — Seções de código não devem ser comentadas — sinaliza blocos comentados/elididos deixados para trás (https://rules.sonarsource.com/javascript/RSPEC-125/)
- **SonarQube / SonarSource** `S1135` — Rastreia usos de tags "TODO" — expõe resíduos de placeholder TODO entregues como código (https://rules.sonarsource.com/javascript/RSPEC-1135/)
- **SonarQube / SonarSource** `S1134` — Rastreia usos de tags "FIXME" (https://rules.sonarsource.com/javascript/RSPEC-1134/)