Comentários Resíduo de Prompt.

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.

// 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" (Comments Everywhere) — "comentários inline excessivos que aumentam drasticamente a carga computacional … e tornam o código mais difícil de revisar e manter" — em 90–100% do código gerado por IA em seu estudo de mais de 300 repositórios.

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.

Por que isso prejudica

• Carga de revisão. Cada linha de narração é ruído que uma pessoa precisa pular. O enquadramento da OX: a IA trabalha como "um exército de desenvolvedores juniores talentosos, mas inexperientes", e "uma revisão de código adequada simplesmente não consegue escalar no ritmo da nova velocidade de produção" — 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 que reformulam o prompt duplicam a intenção do código em prosa; a prosa se desvia conforme o código muda e deixa documentação ativamente enganosa — o clássico smell Comentários de Fowler, em que comentários servem de desodorante.
• 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.

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 ciclo de lint e correção 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 de imediato comentários de bate-papo e narração. Onde um comentário apenas reformula o que o código faz, esse é o sinal para tornar o código autodocumentado — aplique Extrair Método e Renomear Método (ou Extrair Variável para uma única expressão) para que o nome carregue a intenção, e mantenha apenas comentários que expliquem um porquê não óbvio. É o conselho de Fowler para o smell Comentários: quando sentir necessidade de escrever um comentário, tente primeiro refatorar para que o comentário se torne supérfluo.

// 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);
}

// 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á.