Nos últimos anos, especialmente após a pandemia e a explosão da IA, testemunhei um declínio silencioso de uma profissão que se orgulhava de seu pragmatismo e atenção aos detalhes: o desenvolvimento de software.
Não estou prevendo o fim dessa carreira - muito pelo contrário. Mas algo mudou na essência do que nos definia. Antes, éramos reconhecidos não apenas por fazer código que funciona, mas por fazer código que conta uma história. Quantas horas já perdemos em debates apaixonados sobre linguagens, tecnologias, arquiteturas? Éramos pessoas que faziam tecnologia porque amávamos o processo de criação, a arte por trás do código.
E essa paixão sempre foi mais evidente em um detalhe fundamental: a documentação.
Documentar o código que você acabou de escrever era como se você estivesse escrevendo um livro sobre a sua obra de arte, as pessoas gostavam de explicar como as coisas funcionavam, gostavam de falar sobre os programas que faziam e os produtos que foram produzidos com tanto carinho.
A EA recentemente liberou o código fonte de Command & Conquer e eu postei esse tweet:
Saiu o código fonte do Command & Conquer no GitHub e eu tava lendo um pouco dele, não sei quem é o Joe, mas esse código é provavelmente um dos mais bem documentados que eu já vi na minha vida. Saudades de quando a gente tinha código assim... pic.twitter.com/4KiWVROfZ1
— Lucas Santos 🇧🇷🇸🇪 • formacaots.com.br 💎 (@_StaticVoid) March 3, 2025
Esse código foi escrito em 1995 e, sem dúvida, é um dos mais bem documentados que já vi em toda a minha carreira. Mas então parei para pensar: já faz anos que não vejo uma documentação assim. Onde foram parar essas boas documentações?
Nos comentários desse tweet, muita gente disse que o código era feio, que hoje as coisas são diferentes, que jamais o consideraria bem documentado, e por aí vai. O que aconteceu? Como passamos de documentações detalhadas como essa para simples anotações apressadas em READMEs mal feitos?
Eu deixei essa pergunta em um outro tweet, se você quiser dar sua opinião por lá vai ser super legal! 😄
O que aconteceu com a gente?
Sempre foi claro que código é uma ferramenta – nunca duvidei disso, e não duvido agora. Mas o que aconteceu com a gente? Paramos de nos preocupar se as pessoas conseguirão usar ou sequer entender nossos sistemas. Hoje, parece muito mais "eficiente" e "produtivo" simplesmente copiar um código qualquer, colá-lo sem ler nada e ver no que dá.
Eu tenho algumas teorias...
O declínio lento do pensamento crítico
Para promover a Formação TypeScript, rodo anúncios em várias plataformas de tempos em tempos. Talvez você já tenha visto (ou não). Não é segredo que faço isso – sempre fiz, assim como qualquer pessoa que tem um produto digital.
Faço isso há anos sem problemas, mas recentemente publiquei um anúncio um pouco mais "polêmico" e, pelo visto, não consegui transmitir a mensagem como queria. Várias pessoas repetiram exatamente o mesmo comentário, mesmo depois de eu já ter respondido a mesma questão diversas vezes.
Isso aconteceu tantas vezes que fui forçado a bloquear os comentários em todos os anúncios.
Não são os haters ou os comentários que me chateiam. Estou na internet há tempo suficiente para lidar com o ódio inevitável que as pessoas destilam do conforto de seus teclados. O que me incomoda é a total falta de esforço para entender o contexto — ou seja, para ler.
E o mesmo acontece no desenvolvimento. Os devs estão cada vez mais preguiçosos e acomodados, perdendo a curiosidade que antes era um pré-requisito para essa área.
De uma profissão que se orgulhava de ser meticulosa e focada, passamos para uma geração que terceiriza seu pensamento para outra máquina, apenas para repetir exatamente o que ela diz. Novamente:
o que aconteceu com a gente?
Desde que o ChatGPT e outras ferramentas surgiram, a quantidade de pessoas que simplesmente copiam e colam um prompt sem nem sequer ler o que ele diz é absurda.
E não sou só eu dizendo isso do alto de um trono de mármore. Existem diversos relatórios sobre o assunto:
Luca Rossi
Tim Anderson
Bill Doerrfeld
Quase todos apontam a mesma coisa: A qualidade de código está decaindo ano após ano porque as pessoas estão simplesmente copiando código ao invés de pensar.
Tenho muito mais a dizer sobre isso e vou abordar o assunto em outro Backlog.
O ponto aqui é que poucos agora se preocupam em documentar ou dar um pouco mais de atenção ao código que escreve, porque simplesmente:
- É mais fácil pedir para a IA gerar um código na hora, sem considerar o restante da base.
- Copiar todo o código e pedir para a IA explicá-lo em duas linhas.
- Deixar que a IA escreva a documentação.
E há um problema curioso nisso tudo: o código gerado por IA costuma ser muito bem comentado. O resultado? Criou-se o estereótipo de que qualquer código bem comentado só pode ter sido escrito por IA — e não que seja simplesmente um código bem feito e fácil de ler.
Dev bom sabe ler e entender
Muita gente chega falando:
"Ah! Mas o Clean Code é contra comentários blablabla"
E esse é mais um exemplo de como as pessoas pararam de pensar. Clean Code é um livro antigo, de outra época, mas nem por isso condena comentários no código — ele condena comentários inúteis. Por exemplo:
// Soma a+b
function sum (a, b) { return a+b }
É um comentário inútil — descreve o que está acontecendo, mas não por quê. E é aí que está a nuance.
A documentação (seja em comentários ou não) deve explicar o porquê das coisas, não o que o código faz. Isso deve ser claro apenas lendo o código.
"Se você não consegue entender o que o código faz só lendo, então você é um mau dev"
Essa frase me irrita tanto, e por um motivo simples, Veja esse código:
float Q_rsqrt( float number )
{
long i;
float x2, y;
const float threehalfs = 1.5F;
x2 = number * 0.5F;
y = number;
i = * ( long * ) &y;
i = 0x5f3759df - ( i >> 1 );
y = * ( float * ) &i;
y = y * ( threehalfs - ( x2 * y * y ) );
return y;
}Agora tente ler esse código sem nenhum contexto. Conseguiu entender?
Se sim, só existem duas possibilidades: ou você é extremamente inteligente e fora da curva, ou já conhece a história desse bloco.
Entender código é difícil, principalmente porque ele sempre vem com um contexto. É por isso que comentários são tão importantes. Um trecho solto, sem explicação, é como abrir um livro em uma página aleatória e tentar seguir a história a partir dali.
Caso você esteja curioso(a) o código é esse aqui
Mas eu acho que a culpa não é só de devs, mas também de um mindset que eu odeio muito. O de "hustle bro" ou de "indie hacker". Essa é a minha outra teoria.
Ship it! Ship it! Ship it!
Duas palavras definem o mercado de TI de 2019 até hoje (2025): dinheiro e velocidade.
Entre em qualquer site de biblioteca, ferramenta ou framework e você sempre verá alguma variação de "blazing fast", "weeks, not months", e similares. Velocidade e lucro a qualquer custo se tornaram os objetivos principais de praticamente tudo.
A cultura de hustle bro, com seu mantra de "VOCÊ CONSEGUE! ACREDITE EM VOCÊ" e "trabalhe enquanto eles dormem", ganhou força e acabou transformando um mindset que eu admirava, o de indie hacker. Um indie hacker é um empreendedor solo que cria um produto com total controle, sem investidores, sendo independente. Eu sempre amei essa ideia de trabalhar no que você deseja e fazer dar certo. Mas isso mudou quando tudo passou a ser sobre ser mais eficiente e produtivo, como se o dinheiro fosse o único objetivo.
As pessoas estão transitando de um estado de "planejar, aprender e executar" para "executar e ver no que dá".
No mesmo cenário dos criadores de "por que testar? Testar não adiciona valor ao produto", surge a ideia de que "documentação é uma perda de tempo" pelo mesmo motivo. Assim, a documentação é negligenciada, pois, novamente, "bons devs sabem o que acontece no código só de olhar". Documentação, housekeeping e boas práticas são vistos como desperdício, e o foco passa a ser apenas em shipar shipar shipar.
Para exemplificar, vou citar duas figuras emblemáticas do novo "indie hacking", Pieter Levels e Marc Lou, mas longe de serem os únicos, eles são apenas os que fazem mais barulho.
Note que os detalhes são impressionantemente iguais. Bios com sites e rendas mensais, cifrões em todo lugar, a palavra "ship" e "fast" estão bastante presentes.
Para provar meu ponto, um deles está neste momento desenvolvendo um jogo, sem nenhum conhecimento prévio em desenvolvimento de jogos, sem ler documentação, apenas copiando e colando código do Claude Sonnet e esse tweet resume muito do que está acontecendo.
This is like the vibe coding version of the TV show "Alone".@levelsio is stranded in the wilderness, trying to build a multiplayer videogame with nothing but a Cursor subscription.
— George Arrowsmith (@ThatArrowsmith) March 2, 2025
As time goes on, the challenge gets harder: the game gets more complicated, the bugs get… https://t.co/t0YOJsljWl
À medida que os bugs ficam mais difíceis, a solução não é aprender a fazer do jeito certo, mas sim resolver os bugs e criar outros "para ver se funciona". As pessoas estão trocando o ciclo de "planejar, aprender e executar" por "executar e ver no que dá", o que é péssimo, pois ninguém quer estudar nada, só testar e ver o que acontece.
O problema não é o que elas "sabem que não sabem", mas o que "não sabem que não sabem", e ainda assim acreditam que está tudo resolvido. O maior exemplo disso foi a treta recente com o Marc, onde um dos seus produtos passou por sérios problemas porque ele não implementou a segurança necessária no seu "MVP". Coisas que poderiam ter sido resolvidas com 15 minutos de leitura de documentação sobre os casos de uso. Isso me lembra novamente o meme:
Documentações que importam
Para finalizar, quero deixar algumas dicas de como eu vejo boas documentações. Empresas como o Stripe, Vercel, Twillio e Resend para mim são as que mais dominaram a "arte de documentar" as coisas que eles tem. As docs são extremamente bem feitas e fáceis de ler, também são mantidas atualizadas.
E o que torna uma documentação boa?
- Faça a página inicial ser um guia, o Stripe faz isso muito bem, guiando você pelos produtos
- Ensine os fundamentos da sua tecnologia, não só que ela existe lá, a Vercel tem uma página muito boa para isso
- Código deve sempre estar presente na forma de um tutorial, um passo a passo ou guia simples, como na Resend
- Cubra casos de uso comuns entre os usuários com documentações específicas para elas, que nem essa página do SendGrid
Mas como manter a documentação atualizada? O código muda, mas ele não está ligado à documentação... Mas e se estivesse?
Documentação === Código
Tente escrever código que gere a documentação, não o contrário. Em vez de criar e manter a documentação separada, faça com que o código seja a fonte da verdade. Ferramentas como o protobuf ou a spec da OpenAPI são excelentes para manter contratos documentados. Por que não gerar a documentação diretamente a partir delas?
Se você acha que manter a documentação é muito complicado, pare de mantê-la manualmente. Mantenha apenas o código e faça com que ele gere a documentação automaticamente. Não permita atualizar um sem o outro. Existem várias ferramentas que permitem isso tanto com comentários (JS/TSDoc) quanto no próprio código. Eu, por exemplo, já criei uma que transforma rotas diretamente em specs da OpenAPI.
O que quero dizer é que você não precisa manter a documentação separada; você pode delegar essa tarefa ao seu código. Assim, você sempre saberá o que está no código e terá a documentação atualizada sem esforço extra.
Escreva comentários que importam
Comentários devem contar uma história. Se a função é óbvia, não é necessário comentar. A aplicação provavelmente nem notará um comentário a mais ou a falta dele, mas comentários inúteis fazem o oposto do que precisamos.
Quando um comentário ruim é adicionado, você não consegue distinguir um bom de um ruim, e acaba gastando tempo lendo coisas desnecessárias. Ninguém gosta de ler mais do que precisa.
Porém, quando você fornece todo o contexto sobre o motivo de uma função ou até mesmo de uma linha de código, você poupa horas de debugging, tanto suas quanto de outras pessoas no futuro.
Ao contrário do que muitos dizem, documentações, se feitas corretamente, podem trazer muitos benefícios, como uma curva de aprendizado menor e maior facilidade para manter um projeto a longo prazo. Foi graças a documentações como essas que consegui manter este projeto por tanto tempo, por exemplo.
E você? Qual é a sua opinião sobre documentações?