Vibecoding
Como escrever comentário que ajuda em vez de atrapalhar
A IA gera comentário que repete o que o código já diz. Isso não é documentação, é ruído. Comentário útil responde uma pergunta que o código não consegue responder.
Peça código pra uma IA e ele vem comentado. Bastante comentado.
O problema é o tipo de comentário. Quase sempre é assim: uma linha explicando que a próxima linha soma dois valores, logo acima de uma linha que soma dois valores.
Isso não é documentação. É volume.
Por que comentário descritivo é pior que nada
Dois motivos, e o segundo é o que dói.
Ele ocupa espaço sem informar. Quem lê já sabia, porque o código estava ali. A leitura fica mais longa e não fica mais clara.
Ele vira mentira. O código muda e o comentário fica. Seis meses depois existe um comentário afirmando com segurança algo que não acontece mais, e alguém vai acreditar nele antes de ler o código.
Comentário desatualizado é pior que ausência de comentário, porque ausência deixa a pessoa desconfiada e mentira deixa confiante.
O que o código não consegue dizer
Comentário bom responde o que o código é incapaz de responder sozinho. São quatro coisas:
Por quê. A decisão. "Guardamos duplicado aqui porque o relatório antigo lê deste campo e ainda não foi migrado."
O que foi descartado. "Tentamos fazer direto pela API, mas o limite de requisição não aguenta o volume do fechamento."
A armadilha. "Este valor vem como texto, não como número, apesar do nome. É assim que o fornecedor manda."
O que não pode mudar. "A ordem destes dois passos importa: se inverter, o pagamento confirma antes da reserva."
Nenhuma das quatro está no código. Todas se perdem se ninguém escrever.
A regra de uma linha
Antes de escrever, pergunta: isso está no código logo abaixo?
Se está, apaga. Se não está, escreve.
Simples assim, e resolve 90% dos casos.
Onde comentário compensa mais
Nem todo trecho precisa. Os que mais rendem:
Onde tem cálculo com regra de negócio. Prazo, imposto, desconto, arredondamento. O número mágico sempre tem uma origem, e a origem sempre se perde.
Onde tem gambiarra consciente. Toda gambiarra tem motivo. Sem o motivo escrito, ela parece incompetência e alguém vai "consertar" e quebrar.
Onde tem ordem que importa. Sequência que não pode ser trocada e não parece sequencial.
Onde tem exceção. O caso especial que existe por causa de um cliente, uma lei ou um histórico.
Onde não compensa
Função com nome claro fazendo coisa óbvia. Bloco simples. Configuração padrão.
E o clássico: comentário que explica sintaxe da linguagem. Se a pessoa não sabe o que aquela construção faz, o comentário não é o lugar de ensinar.
O que fazer com o que a IA gera
Entra na revisão, junto com o resto.
Apaga o que só repete o código. Mantém o que explica intenção, quando existir. Acrescenta o porquê, que ela não tinha como saber.
Esse último ponto merece ênfase: a IA não escreve o motivo porque o motivo nunca foi dito a ela. Ele estava na sua cabeça. Ela só tinha o código como fonte, e código não contém intenção.
É a mesma limitação de quando você volta no projeto seis meses depois: o que faz dá pra reler, o porquê não.
O teste final
Lê seu comentário e pergunta: se eu apagar o código e deixar só isso, alguém entende a decisão?
Se sim, é um bom comentário. Se não, provavelmente ele só estava repetindo o que já estava escrito.
Código diz o que acontece. Comentário existe pra dizer por quê.
A decisão é sua.
Perguntas frequentes
Perguntas rápidas
+Por que comentário descritivo é ruim?
Porque duplica informação que já está no código e desatualiza quando o código muda. O resultado é um comentário que descreve algo que não acontece mais, o que é pior que não ter comentário.
+O que um bom comentário responde?
Por que aquilo foi feito assim, o que foi tentado antes, qual armadilha existe naquele trecho e o que não pode ser mudado sem quebrar outra coisa. São informações que não estão no código.
+A IA não escreve bons comentários?
Ela escreve comentários corretos e descritivos, porque só tem o código como fonte. O motivo da decisão estava na sua cabeça e nunca foi dito a ela, então ela não pode escrever.
+Devo remover os comentários que a IA gerou?
Os que apenas repetem o código, sim. Eles aumentam a leitura sem acrescentar nada e viram mentira com o tempo. Mantenha os que explicam intenção.
Continue lendo
Como documentar um sistema que a IA escreveu
Documentação longa ninguém escreve e ninguém lê. Existe uma versão curta que cabe em uma página e resolve 90% do problema, principalmente quando quem escreveu o código foi a IA.
VibecodingComo subir pra produção numa sexta sem medo
A regra de não subir na sexta existe porque o processo é ruim, não porque sexta é perigosa. Com quatro coisas no lugar, o dia da semana para de importar.
VibecodingO agente de código entrou no canal do time. Ver não é revisar
O Slack lançou canais onde agentes de IA programam na frente de todo mundo, com Claude, Copilot, Devin, ChatGPT e Vercel. É a melhor notícia de governança do ano e a maior armadilha de teatro de revisão.