Por favor, mantenha as explicações de código simples

• Em revisões de código, quando explicações longas vêm junto com um diff grande, fica difícil para quem revisa identificar o ponto principal: o motivo da mudança. Por isso, mensagens de commit, descrições de merge request e comentários devem ser concisos
• As explicações devem focar mais em por que isso mudou do que em o que mudou, já que grande parte das alterações pode ser verificada no próprio código
• Explicações longas que tentam incluir todo o contexto de uma vez podem prejudicar a concentração de alguns revisores e desacelerar a revisão
• Em revisões de merge, commits atômicos são especialmente importantes; pequenas correções podem ser feitas com git amend, e a organização antes da mesclagem pode ser resolvida com rebase ou squash
• Mesmo usando ferramentas de LLM, escrever você mesmo os comentários, explicações e mensagens de commit ajuda mais na compreensão do código e na acessibilidade da revisão

---

Em explicações de revisão, foque no “por quê” mais do que no “o quê”

• Em revisão de código, quando descrições, commits e merge requests ficam cheios de informação em excesso, a carga para quem revisa aumenta
• Em vez de listar longamente as mudanças, o essencial é deixar claro por que a mudança foi feita
• O próprio código consegue mostrar a maior parte das alterações, e o contexto que faltar pode ser perguntado pelo revisor
• Explicações escritas como textos longos podem tornar a revisão mais lenta para pessoas que têm dificuldade de manter a concentração
• Mensagens de commit, descrições de merge request e comentários no código funcionam melhor quando são claros, diretos e trazem apenas a informação necessária

Pedido sobre organização de commits e uso de LLM

• Os commits devem ser especialmente atômicos em revisões de merge, e cada mudança deve poder ser entendida de forma independente
• Pequenas correções podem ser incorporadas com git amend, e antes da mesclagem é possível organizar tudo com rebase ou squash
• Mesmo ao usar ferramentas de LLM, a ideia é que comentários, explicações e mensagens de commit sejam escritos pela própria pessoa
  • O processo de escrever diretamente ajuda a entender melhor as mudanças
  • Explicações escritas diretamente podem ser mais fáceis de acessar para quem revisa
• Também aparece a opinião pessoal de que, se possível, é melhor evitar ferramentas de LLM
• Houve reação ao uso da expressão acessibilidade, mas o ponto central é o pedido para tornar as explicações de code review mais concisas e fáceis de revisar

[GN⁺]

Opiniões no Lobste.rs

• É preciso ter cuidado ao equiparar exigências de acessibilidade a preferências pessoais específicas com muita facilidade
  Ter ADHD não significa necessariamente que odiar mensagens de commit longas seja uma característica universal de quem tem ADHD, e acessibilidade está mais próxima de adaptações razoáveis que não imponham carga excessiva ao usuário em geral do que de “fazer tudo do jeito que uma pessoa com ADHD gosta”
  Por isso, muitos recursos de acessibilidade ficam por trás de configurações que cada pessoa pode escolher, como alto contraste, redução de movimento e modo escuro

  • Eu poderia ter escrito isso com mais clareza, mas meu AuDHD precisa de certas condições para conseguir trabalhar e funcionar direito
    Blocos longos de texto, por exemplo quando uma mudança pequena vem acompanhada de uma explicação de duas páginas A4, podem bloquear totalmente meu trabalho, e forçar a leitura pode levar ao burnout
    Acho que eu deveria ter dito algo como “essa é uma necessidade de acessibilidade minha, e sei que há muitas pessoas parecidas”
    Ainda assim, talvez isso possa ser visto como preferência e não como exigência, mas é um pedido para que, ao colar muralhas de texto geradas por LLM em mensagens de commit, considerem pessoas como eu
  • Varia de pessoa para pessoa, mas acho que “vá direto ao ponto” é sim uma característica central do ADHD em muitos casos
    Até do ponto de vista de acessibilidade, todo mundo se beneficia desse ajuste, então não parece haver motivo para se opor
  • Pela minha experiência, boa parte das dificuldades desnecessárias enfrentadas por pessoas neurodivergentes e com deficiência surge de tratar necessidades de acessibilidade como preferência
    Quando a acessibilidade aumenta, até quem não precisa estritamente desses recursos para partir de uma linha de igualdade também se beneficia, então ir nessa direção é algo bom

• Mesmo antes da IA, eu sempre preferi comentários excessivamente detalhados, e muita gente com quem trabalhei achava isso curioso
  Por exemplo, existe este método: https://github.com/ghostty-org/ghostty/…
  Nos últimos 15 anos, independentemente da linguagem, em geral escrevi nesse estilo, e na era da IA passei a explicitar essa abordagem também no AGENTS.md
  O arquivo e os comentários do link foram todos escritos por humanos, sem uso algum de IA
  O motivo é simples: isso força uma regra de registro duplo em que comentário e código precisam bater
  Se os dois não batem, então o comentário está errado, ou o código está errado, ou ambos estão errados; e só de perguntar “qual dos dois está certo?” já consegui encontrar muitos problemas
  No fim, sendo o próprio projeto, cada um pode comentar do jeito que preferir

  • Eu também ouço de vez em quando a brincadeira amigável de que escrevo mais comentários do que código, mas adoro esse tipo de comentário
    Quando releio o código depois, ele preserva o contexto de decisões locais tomadas na época, e também ajuda revisores ou pessoas que estão vendo aquilo pela primeira vez a construir contexto
    Esses comentários podem ser prolixos, mas não são os “detalhes desnecessários” de que o texto fala, e o exemplo compartilhado parece um bom caso do conselho “explique o porquê, não o quê”
  • Comentários assim são excelentes
    Como no exemplo, um comentário explicando por que usuários de macOS passaram a colocar configurações de shell em ~/.bash_profile e a esperar um shell de login fornece contexto útil sobre por que certa decisão foi tomada
    Mas, voltando aos LLMs, pessoalmente ainda não vi comentários gerados por LLM com essa qualidade
    Normalmente eles só repetem o que já é óbvio lendo o código, algo como faz foo(), depois faz bar(), e por fim faz baz
  • O tipo de comentário no link não tem problema algum
    O problema é a bagunça de enfiar tabelas enormes e listas com marcadores até em mudanças minúsculas
  • Eu realmente agradeço esse nível de detalhe, mas pessoalmente prefiro que isso fique na mensagem de commit do commit que adicionou esse método, e não nos comentários
    Mensagens de commit permanecem como um registro sempre alinhado ao momento do código, enquanto comentários podem se descolar com o tempo
  • O comentário que começa na linha 1467 é uma obra-prima, dá para sentir o cansaço dali

• No trabalho, tentei colocar com delicadeza no template de PR algo como “explique diretamente a motivação desta mudança e as decisões de design importantes que o revisor deve observar”
  Só que 9 de 10 vezes o LLM usado no momento ignora o template inteiro e cospe uma explicação longa, com número de testes adicionados, caixas de seleção de aprovação e longas digressões sobre coisas triviais
  Isso realmente torna a revisão muito prazerosa

  • Tenho o mesmo problema no trabalho
    Não sei quem achou que seria uma boa ideia enfiar ferramentas de mensagens de commit geradas por LLM em tudo quanto é lugar, mas o resultado é que surge dentro dos commits o problema de https://noslopgrenade.com/
    Em mensagens de commit ou descrições de pull request não há contexto útil como motivação da mudança, decisões de design ou justificativas; tudo vira parágrafos descrevendo detalhes de implementação que já seriam evidentes só lendo o código
  • Eu também vi esse mesmo comportamento
    Estou pensando em adicionar ao agents.md algo como “ao escrever mensagens de commit, consulte commit-messages.md”
    Em commit-messages.md, daria para colocar diretrizes para mensagens de commit como proibir checkboxes de testes aprovados/reprovados e resumir testes individuais em vez de listá-los um por um, ou simplesmente omiti-los

• A única hora em que escrevo comentários dizendo o que estou fazendo, e não por que estou fazendo, é quando não tenho certeza de que aquela forma está certa
  Um dos grandes causadores recorrentes de sofrimento é regex

  • Igual aqui
    Há momentos em que é preciso explicar tudo de forma bem sólida, mas hoje em dia vejo até mudanças pequenas, como renomear uma variável, vindo acompanhadas de uma explicação gigantesca

• Curiosamente, eu sempre ouvi mais que minhas mensagens de commit são curtas demais

  • A discussão deste texto fica lado a lado com a do post Chesterton middle finger, que reclama do problema oposto: explicações curtas demais
  • Pode até ser curto demais, mas também não faz sentido enfiar ali um romance inteiro
  • LLM realmente escreve demais
    Por isso configurei o claude para nunca escrever comentários, porque eu acabava apagando manualmente 98% e reescrevendo os 2% restantes mesmo assim

• Em geral gosto de mensagens de commit bem explicativas, mas tendo a preferir uma estrutura de artigo de notícias, colocando primeiro a informação mais importante e depois os detalhes menos importantes, mas ainda relevantes
  Por exemplo, no título coloco a informação mais importante da forma mais densa possível, no primeiro parágrafo explico a mudança com frases menos comprimidas e, nos parágrafos seguintes, deixo detalhes adicionais que não precisam ser lidos com atenção a menos que seja realmente difícil entender a natureza da mudança no código
  Acho que a importância das mensagens de commit para quem vai ler o código no futuro é subestimada
  Quando estou cavando um codebase e quero entender por que certo bloco ficou daquele jeito, nunca me decepcionei ao chegar via git blame a uma mensagem de commit que explicava em detalhes exaustivos que aquela abordagem aparentemente desajeitada era, na verdade, a opção que restou depois de várias abordagens melhores na aparência, mas incompletas
  Voltando ao ponto do autor, colocar marcadores explícitos na comunicação é um bom ajuste e útil de forma geral
  Dá para colocar no meio da mensagem de commit uma frase como “se você está revisando este código, pode parar de ler aqui”

• Dizer “os detalhes desnecessários podem ser perguntados se necessário” presume de forma ousada que aquela pessoa continuará por perto
  Comecei a escrever mensagens de commit com bastante cuidado quando passei a contribuir para um codebase FLOSS com mais de 10 anos
  A única forma de descobrir mais sobre por que o código existia daquele jeito era a arqueologia de git, e aprendi a usar o vc-annonate do Emacs para rastrear isso com facilidade
  Mesmo em código de trabalho, já houve várias vezes em que o autor original do codebase que eu mantinha já tinha saído havia muito tempo
  Mensagens de commit não são lidas só durante review; na verdade, muitas UIs de review escondem as mensagens de commit
  O problema parece ser menos a mensagem de commit longa em si e mais a mensagem de commit mal escrita
  A diretriz “mensagens de commit, descrições de merge request e comentários de código devem ser claros, diretos ao ponto conforme a necessidade e explicar o porquê, não o quê” parece boa
  O problema também pode ser a pessoa que antes só escrevia Fix Bugz 🚀️ e agora, seguindo as “boas práticas”, passa a escrever mensagens de commit com LLM
  Minha hipótese é que a maioria das pessoas não escreve mensagens de commit porque não as lê, e não as lê porque a energia de ativação para procurá-las é alta quando se depende de algo como a interface web do GitHub para navegar pelos commits

  • “os detalhes desnecessários podem ser perguntados se necessário” é uma fala sobre o review
    Se a informação for importante, ela pode ser deixada em comentários ou adicionada à mensagem de commit
    O KDE usa Gitlab há alguns anos

• No longo prazo, é preciso equilíbrio para uma arqueologia de git bem-sucedida pelas gerações futuras
  Muitas vezes, mais tarde não dá para perguntar sobre aqueles detalhes que pareciam desnecessários por causa de mudanças de equipe ou porque o contexto simplesmente se perdeu da memória das pessoas
  O melhor momento para registrar esse contexto é quando ele ainda existe
  O que você realmente quer pode ser colocar os detalhes importantes primeiro, de uma forma claramente separada, como um resumo

• PRs ou explicações de código não servem para o que foi feito, e sim para por que foi feito
  Elas precisam dizer por que o código tem esse formato e quais são as razões por trás disso
  Isso é bom para o review e também para, mais tarde, encontrar no histórico do git por que o código ficou daquele jeito

• Manter explicações de código simples é importante
  Porque aquilo que não dá para entender ou em que não dá para se concentrar não pode ser lido
  Ao mesmo tempo, no desenvolvimento de software muito contexto se perde, e agora esse contexto muitas vezes existe só na cabeça de quem escreveu, de quem conversou com o autor ou de quem examinou o código a fundo
  Mas acho que esse contexto precisa ficar mais entrelaçado com o código, não menos
  Como nem sempre é possível falar com o autor, isso deve ser escrito em algum lugar sempre acessível e atualizado junto com o código
  No fluxo de desenvolvimento da maioria dos times hoje, o lugar mais adequado para isso é a mensagem de commit do git
  É bom escrever um resumo no topo, mas eu também recomendaria deixar explicações adicionais sobre a mudança no código
  Se você externalizar o contexto, até mesmo aquilo que agora não parece importante, o seu eu do futuro vai agradecer
  No futuro, será preciso uma abordagem melhor do que colocar esse contexto só em mensagens de commit, e é por isso que pessoalmente gosto de programação literária, que dá mais espaço para explicar o “o quê” e o “porquê” do código