TODO na verdade não é algo "para ser resolvido"

• Algumas equipes adotam políticas como registrar todos os comentários TODO no bug tracker ou apagar automaticamente TODOs com mais de 1 ano, mas essas práticas não são recomendadas
• Comentários TODO não servem apenas para coisas que só têm valor se forem concluídas, mas funcionam como um snapshot do cérebro que registra contexto e ideias do momento em que o código foi escrito
• TODOs importantes devem ser gerenciados como issues, mas a maioria é só uma anotação de baixa prioridade ou de edge cases
• Um TODO bem colocado dá ao futuro leitor do código uma pista sobre a intenção do autor na época quando ele estiver pensando "será que posso refatorar esta parte?"
• O valor do TODO não está em ser concluído, mas em registrar contexto, intenção e possibilidades, ajudando na manutenção futura e na colaboração

---

Comentários TODO: precisam mesmo ser resolvidos?

• Em algumas organizações, há regras para registrar todo TODO no bug tracker ou removê-lo automaticamente após certo período (mais de 1 ano)
• Mas essa abordagem é, na prática, ineficiente e perde a essência do TODO — ele não só ganha valor quando é de fato resolvido

O verdadeiro valor do TODO

• Por exemplo,

  // TODO: 다음 주 출시 전에 이 파일의 뒷부분을 완성해야 함  
  

  um comentário assim pode realmente precisar de acompanhamento

• Mas um bom TODO normalmente é algo como

  // TODO: 사용자가 이 버튼을 트리플 클릭할 경우, 핸들러에서 \[xyz] 오류 발생  
  

  que serve para registrar edge cases ou ideias de melhoria estrutural que não puderam ser feitas agora, além de situações que passaram batido, tudo isso com contexto

TODO não é "planejamento", é um "canal"

• A maioria dos TODOs, na prática, tem baixa prioridade e não precisa ser tratada imediatamente
• Eles servem para transmitir ao futuro leitor do código as dúvidas, julgamentos e o contexto do autor no momento em que escreveu
• Quando alguém ler esse código no futuro e se perguntar "posso mudar a estrutura aqui?", o TODO ajuda a entender a intenção original do autor

O efeito de um TODO bem escrito

• TODOs no código às vezes trazem pistas importantes sobre possíveis problemas, oportunidades de melhoria estrutural e edge cases ainda não tratados
• Mesmo quando não são exatamente um plano de resolução, eles têm grande papel em transmitir contexto sutil na colaboração e na manutenção
• No fim, comentários TODO funcionam como um registro valioso que aumenta a compreensão do código e sua futura manutenibilidade

Conclusão

• TODOs não têm valor apenas quando são concluídos; eles funcionam como um canal de comunicação com futuros leitores do código, preservando os pensamentos, intenções e contexto do autor

[GN⁺]

Comentários do Hacker News

• Eu sou do time de que "TODO deve sempre estar ligado a uma issue concreta"
  Acho que há três formas de lidar com um TODO antes do merge
  1. Abrir uma issue — se for realmente algo a fazer, vale gastar uns 20 segundos para registrar e acompanhar
  2. Resolver na hora — se for algo pequeno demais para virar issue, então resolva antes do commit
  3. Transformar em comentário — se não vale a pena corrigir nem acompanhar, mas você quer lembrar disso, recomendo deixar como um comentário normal no código
  Se você se preocupa com saúde, TODO também faz bem quando é acompanhado, como comer brócolis
  • Acompanhar em um sistema externo não é só abrir a issue; há esforço contínuo com categorização, gestão de backlog, reclassificação, fechar quando concluir etc.
    Uma issue registrada em sistema externo pode não ficar visível para os desenvolvedores que mexem naquela parte do código
    Se o custo de acompanhar até coisas simples que dariam para corrigir fácil não compensa, deixar como TODO no código pode ser mais eficiente
    TODOs no código ficam visíveis de imediato quando se trabalha naquela parte e também são fáceis de remover durante refatorações
  • O autor do texto parece apoiar basicamente a opção 3 (deixar como comentário comum)
    Mas é uma pena que ele não tenha explicado claramente a diferença entre um comentário TODO e um comentário comum
    O próprio termo TODO tem um impacto visual forte e deixa claro de imediato que tipo de comentário é
    Acho um pouco duvidoso defender que um comentário TODO não precisa ser entendido literalmente como "TO DO"
    Em geral concordo com a opinião do texto, mas acho que a melhora seria simplesmente deixar como comentário comum
  • Disseram que "basta investir 20 segundos para registrar e gerenciar", mas isso já é justamente o TODO
    Se for subir em um sistema de tickets, vai levar mais de 20 segundos e, em vez de ajudar, tende a causar distração
  • Seria ótimo se rastrear levasse 20 segundos, mas (por ser empresa grande) criar um ticket no JIRA exige mais de 10 campos obrigatórios
  • Eu uso uma única regra: todo TODO precisa ter um número de ticket
    // TODO: improve the routing https://jira.com/whatever/TIX-1234
    O motivo é que, se o comentário virar órfão, ninguém mais sabe por que ele foi deixado ali
    Se você deixar só um comentário, depois alguém vai esquecer o propósito e o contexto
    Então, na minha visão, é preciso ou criar o ticket ou resolver na hora
• Eu faço grep separando assim
  FIXME: algo claramente errado ou quebrado, prioridade máxima
  XXX: algo feio de ver ou com premissa errada, alta prioridade
  TODO: algo em que algum dia será preciso implementar uma abordagem/categoria/ramo totalmente novo
  NOTE: para transmitir informação mais importante do que um comentário simples
  Eu trabalho principalmente com engines legadas/sem manutenção, e aqui "o código é a verdade", então não crio JIRA; vou lendo e corrigindo na hora
  • Eu uso assim
    TODO: algo indispensável antes do release, requisito obrigatório. Se não for esse o caso, deve ir para outra categoria. É algo que bloqueia o release
    FUTURE: algo que um dia talvez vire TODO, normalmente opcional, como projeto estrutural
    MAYDO: seria legal ter, mas não faz falta
    PERF: vale fazer quando for preciso mais desempenho
    E também uso tags semânticas relacionadas ao domínio
    Na minha opinião, TODO não é code smell; é algo que se acumula naturalmente nas partes centrais da base de código
  • Eu uso XXX como uma nota pessoal de "consertar obrigatoriamente antes do próximo PR"
    Quando quero levar isso a sério, configuro a CI para rejeitar código que contenha essa string
    Nesse sentido, XXX é minha prioridade mais alta
  • Gosto desse estilo. Em um projeto, a CI rejeitava automaticamente código com FIXME, e TODO era rejeitado se não tivesse ticket de issue
    Em ordem de prioridade, de cima para baixo
    FIXME: para manter o foco. Precisa ser resolvido antes do merge ou antes de o código ser considerado concluído
    XXX: precisa ser corrigido em breve. Funciona agora, mas deve ser ajustado logo
    TODO: precisa ser revisitado depois. O código pode ser usado perfeitamente. Prioridade menor que XXX
    NOTE: ajuda quem vier depois, explicando algo incomum ou importante de saber
  • Eu faço algo parecido. Em caminhos de código ainda incompletos, mas contornáveis, coloco assert em vez de FIXME
    TODO serve para deixar possíveis tarefas como refatoração, desempenho ou melhoria de clareza
    NOTE eu uso para registrar contexto histórico ou linha de raciocínio que não fica óbvia à primeira vista
  • Na teoria isso é bom, mas acho que esse tipo de convenção é inútil sem suporte de ferramentas
    Ainda mais se assumirmos que é trabalho em equipe
    Isso não quer dizer que a ideia em si não tenha valor — acho que essas ferramentas deveriam existir ou ser criadas
• Isso me lembra a frase de que o perfeito é inimigo do bom
  Essas dívidas técnicas ou code smells na verdade deveriam ser melhor rastreadas/registradas/explicadas, mas se você manda fazer isso de um jeito que derruba a produtividade, como no JIRA, o resultado é que ninguém registra nada
  Pelo menos, se houver um TODO no código, isso fica registrado em algum lugar
  TODO faz sentido porque também é uma "coisa a fazer" de verdade
  • Em codebases grandes, TODOs de várias pessoas podem se misturar e virar bagunça, mas em projetos individuais isso é um bom meio-termo
    "Eu sei que isso poderia ser melhor, mas não vou interromper meu fluxo de propósito por causa disso. Não está quebrando a funcionalidade, só ficaria melhor se fosse feito."
    Quando o destaque de TODO no editor aparece de vez em quando, isso ajuda quando bate vontade de resolver algo rapidinho
    Mas a maioria dos TODOs fica para sempre ou, na prática, quase nunca é resolvida
  • Às vezes eu deixo TODO porque quero marcar no código um sinal de que há algo a tratar
    Mesmo que isso seja registrado no JIRA, GH Issues etc., no fim das contas o registro precisa estar conectado
    E, se você deixar apenas uma referência, isso pode perder o sentido mais tarde; então o comentário também precisa de explicação
  • Já existe até recurso de servidor MCP em que a IA cria ticket no JIRA e executa isso direto no Cursor
  • Acho muito melhor deixar isso em mensagem de commit do git
    Muitos commits, na prática, não comunicam bem o conteúdo
    Em vez de manter o costume antigo de deixar TODO, seria melhor incentivar o uso de ferramentas melhores
    Muitos desenvolvedores fazem commit com pouca frequência e acabam colocando várias tarefas diferentes de uma vez
    E muita mensagem de commit acaba sendo algo sem sentido, como "updating somefile.py"
• Isso é uma questão de estilo. Cada pessoa pode ter definição e cultura diferentes para TODO
  Na minha codebase, TODO é usado do jeito descrito aqui
  TODO serve para documentar a implementação, especialmente o que está faltando — não significa necessariamente que precise ser feito
  Na minha opinião, deixar uma lista real de tarefas no próprio código não faz muito sentido. As prioridades mudam o tempo todo; algo podia parecer importante quando foi escrito, mas depois não ser mais, e às vezes surge um problema inesperado que acaba tendo prioridade maior
  Não dá para continuar abrindo PR só para atualizar comentários TODO
  Se quiser registrar tarefas, é melhor gerenciar isso fora do código, num issue tracker ou até num documento de texto fácil de atualizar
• O título é meio caça-cliques, mas concordo totalmente com o conteúdo
  Eu mesmo acabei de registrar uma situação excepcional e extremamente rara com #TODO. Em dois anos isso nunca aconteceu de fato, mas ajuda quando no futuro eu quiser saber por que não tratei essa parte
  Entendo quem diz que esse tipo de coisa às vezes deveria ser só comentário comum. Depende da natureza da codebase, e num ambiente como o meu, de equipe de 2 pessoas, o jeito com TODO funciona bem
  • Nosso time usava // TBD: [...] para esse tipo de caso. Era um truque para o pessoal obcecado com TODO não perceber
• É preciso existir algum lugar para registrar problemas conhecidos que claramente têm valor, mas não precisam ser rastreados
  Não há plano real de corrigir isso, mas quando sobrar tempo talvez valha a pena procurar com um ctrl-F para ver se ainda faz sentido limpar
  Acho irracional que tantas ferramentas e processos tratem TODO como code smell
  • Eu, na verdade, ainda não passei por esse tipo de caso
    Para mim, no fim é só uma questão de prioridade, um tipo de janela quebrada (na famosa metáfora do Pragmatic Programmer)
    Se você realmente decidiu não corrigir, então é melhor registrar isso na documentação do software
• No exemplo dado no texto

  // TODO: If the user triple-clicks this button, the click handler errors because [xyz]
  isso me parece mais um comentário comum do que um TODO de verdade
  Esse tipo de comentário explicativo claramente ajuda, mas é meio estranho chamar isso de TODO
  TODO deveria indicar algo que realmente precisa ser feito, ou seja, deixar claro que isso tem de mudar, como em "esta função deveria retornar um valor diferente conforme XYZ"
  Nesse sentido, TODO não deveria ficar enterrado no código, e sim no issue tracker
  Pela minha experiência, TODO é só uma forma de justificar sacrificar a qualidade do código para conseguir aprovação rápida do PR. Na prática, quase nunca é executado, e só fica aquela ideia de "algum desenvolvedor júnior com tempo sobrando resolve isso um dia"

  • Comentário serve para explicar por que esse código funciona desse jeito
    Por exemplo, se você escrever apenas
    // If the user triple-clicks this button, the click handler errors because [xyz]
    assim, não fica claro se isso é um bug ou se é comportamento intencional
    TODO é um sinal simples de "há algo imperfeito aqui; leve isso em conta ao trabalhar"
    Se for algo que realmente precisa ser resolvido, o certo é rastrear em outro lugar
    Mas acho que, se você tentar reduzir TODO demais, o resultado é só aumentar a quantidade de código sem documentação
  • Não acho esse exemplo um comentário TODO muito bom
    Nesse tempo, seria melhor simplesmente corrigir o bug ou deixar um comentário do tipo "triple click é ignorado por causa de [xyz]"
    Se você já descobriu o gatilho e a causa, então na minha opinião 80% do trabalho já foi feito
  • Isso dá para ver mais como "pular". Em muitos casos, não tem problema nenhum não fazer
    O problema é quando se assume que o código funciona perfeitamente, mesmo não funcionando
    O melhor TODO que já vi era algo como "TODO: encrypt this" em código de segurança
    Graças a isso, qualquer pessoa percebia de imediato que o código não estava criptografando, e diminuía a dúvida se aquilo já era tratado por modularização em outro ponto ou se haveria risco de criptografar em duplicidade
  • O exemplo dado está mais para FIXME do que para TODO
    É claramente um erro, só que com baixa necessidade de tratamento
• Discordo fortemente
  Se você não vai registrar como bug nem realmente trabalhar nisso, preferia que não deixasse TODO
  // TODO: If the user triple-clicks this button, the click handler errors because [xyz]
  Isso é apenas um registro de comportamento. O certo seria remover a palavra TODO
• Eu também uso de forma hierárquica
  FIXME eu uso quando algo realmente precisa ser corrigido ou quando o próximo passo está muito claro
  TODO eu uso para pensamentos mais vagos do que isso, ou simplesmente para tirar algo da cabeça e conseguir focar na próxima tarefa
  Pode ser quando a ideia ainda não amadureceu, quando não tenho certeza de que realmente precisa ser feito, ou quando estou esperando algo relacionado, entre outras situações
  Se eu não registrar, aquilo fica voltando à cabeça e me atrapalha; só de escrever, seja TODO ou qualquer outra coisa, já dá um alívio psicológico enorme
• Eu vejo comentários como evidência de pouca habilidade para escrever código
  Seria ótimo conseguir escrever código que desse para entender diretamente, sem comentários
  Ainda assim, se até eu mesmo não vou entender depois por estar confuso demais, acabo escrevendo comentário
  O triste é que, quando alguém altera o código depois e não atualiza o comentário, isso só cria mais confusão
  Acho que TODO não deveria existir em código com commit feito; o lugar certo para isso é um sistema de gestão de projeto ou de issues