Les TODO ne sont pas vraiment faits pour être « traités »

 (sophiebits.com)
15 points par GN⁺ 2025-07-23 | 1 commentaires | Partager sur WhatsApp
  • Certaines équipes appliquent des politiques consistant à enregistrer tous les commentaires TODO dans un bug tracker, ou à supprimer automatiquement les TODO âgés de plus d’un an, mais cette pratique est déconseillée
  • Un commentaire TODO n’a pas de valeur uniquement s’il est nécessairement accompli ; il sert aussi de snapshot du cerveau, en conservant le contexte et les idées présents au moment où le code a été écrit
  • Les TODO importants doivent bien sûr être gérés comme des issues, mais la plupart sont surtout des notes de faible priorité ou sur des cas limites
  • Un TODO bien placé donne aux futurs lecteurs du code un indice sur l’intention de l’auteur à l’époque lorsqu’ils se demandent : « Peut-on refactorer cette partie ? »
  • La valeur d’un TODO ne tient pas à son exécution, mais au fait qu’il consigne contexte, intention et possibilités, afin d’aider la maintenance et la collaboration futures

Les commentaires TODO, faut-il vraiment les traiter ?

  • Dans certaines organisations, des règles imposent d’enregistrer tous les TODO présents dans le code dans un bug tracker, ou de les supprimer automatiquement après un certain délai (plus d’un an)
  • Mais cette approche est en réalité inefficace et passe à côté de la nature même des TODO : leur valeur ne vient pas forcément du fait qu’ils doivent être traités

La vraie valeur des TODO

  • Par exemple,

    // TODO: terminer la seconde moitié de ce fichier avant la sortie de la semaine prochaine

    un commentaire comme celui-ci peut effectivement mériter un suivi

  • Mais un bon TODO sert le plus souvent à

    // TODO: si l’utilisateur clique trois fois sur ce bouton, le handler provoque l’erreur \[xyz]

    noter un cas limite, ou à consigner avec son contexte une idée d’amélioration structurelle impossible à faire tout de suite, ou encore une situation oubliée

Le TODO n’est pas un « plan », mais un « point d’entrée »

  • La plupart des TODO sont en pratique de faible priorité et n’ont pas besoin d’être traités immédiatement
  • Ils servent à transmettre aux futurs lecteurs du code les réflexions, le jugement et le contexte de l’auteur au moment de l’écriture
  • Plus tard, lorsque quelqu’un relit le code et se demande « Peut-on changer la structure ici ? », un TODO peut aider à comprendre l’intention de l’auteur à l’époque

Les effets d’un TODO bien rédigé

  • Dans le code, les TODO donnent parfois des indications importantes sur des problèmes potentiels, des possibilités d’amélioration structurelle ou des cas limites non traités
  • Même s’ils ne constituent pas forcément un plan de résolution, ils jouent un rôle majeur dans la collaboration et la maintenance en transmettant des nuances de contexte
  • En fin de compte, les commentaires TODO sont de précieux éléments qui améliorent la compréhension du code et sa maintenabilité future

Conclusion

  • Un TODO n’a pas besoin d’être terminé pour avoir de la valeur : il constitue un canal de communication avec les futurs lecteurs du code, en laissant les pensées, l’intention et le contexte de l’auteur

À lire aussi

1 commentaires

 
GN⁺ 2025-07-23
Avis Hacker News
  • Je considère que « les TODO devraient toujours être reliés à un ticket concret ».
    À mon avis, il y a trois façons de traiter un TODO avant le merge :
    1. Créer un ticket — si c’est vraiment quelque chose à faire, ça vaut le coup d’y consacrer 20 secondes pour le noter et le suivre
    2. Le faire tout de suite — si c’est trop mineur pour devenir un ticket, il faut le régler avant le commit
    3. Le transformer en commentaire — si ça ne mérite ni correction ni suivi, mais que vous voulez vous en souvenir, je recommande de le laisser comme commentaire de code classique
    Pour votre santé de projet, prendre l’habitude de suivre les TODO, c’est un peu comme manger des brocolis.
    • Suivre quelque chose dans un système externe implique un surcroît d’effort continu : création du ticket, catégorisation, gestion du backlog, reclassification, fermeture une fois terminé, etc.
      Un ticket enregistré dans un système externe peut être peu visible pour les développeurs qui touchent réellement à cette partie du code.
      Si le coût de suivi ne vaut pas la peine pour des choses simples à corriger, laisser un TODO dans le code est plus efficace.
      Les TODO dans le code sautent aux yeux quand on travaille sur cette zone, et on peut aussi les supprimer facilement lors d’un refactoring.
    • L’auteur de l’article semble soutenir par défaut l’option 3 (laisser un simple commentaire).
      Mais c’est dommage qu’il ne précise pas clairement la différence entre un commentaire TODO et un commentaire ordinaire.
      Le terme TODO lui-même a un impact visuel fort qui permet d’identifier immédiatement le type de commentaire.
      Je trouve un peu douteux d’affirmer qu’il ne faut pas forcément comprendre TODO comme « à faire ».
      Je suis globalement d’accord avec l’article, mais je pense qu’il vaudrait mieux laisser un commentaire normal.
    • On dit « il suffit d’investir 20 secondes pour l’enregistrer et le gérer », mais au fond c’est justement ce qu’est un TODO.
      Si on le met dans un système de tickets, cela prend non seulement plus de 20 secondes, mais c’est aussi plus distrayant qu’utile.
    • Ce serait bien si le suivi prenait 20 secondes, mais chez moi (grande entreprise), créer un ticket JIRA impose plus de 10 champs obligatoires.
    • Je n’utilise qu’une seule règle : chaque TODO doit obligatoirement contenir un numéro de ticket.
      // TODO: improve the routing https://jira.com/whatever/TIX-1234
      La raison, c’est que si un commentaire devient orphelin, plus personne ne sait pourquoi il a été laissé là.
      Si on ne laisse qu’un commentaire, quelqu’un finira plus tard par oublier son usage et son contexte.
      Donc selon moi, il faut soit créer un ticket, soit régler le sujet immédiatement.
  • Moi, je fais des grep en distinguant les catégories suivantes :
    FIXME: partie manifestement incorrecte ou cassée, priorité maximale
    XXX: partie moche ou fondée sur une mauvaise hypothèse, priorité élevée
    TODO: endroit où il faudra un jour implémenter une approche / catégorie / branche complètement nouvelle
    NOTE: pour transmettre une information plus importante qu’un simple commentaire
    Je travaille surtout sur des moteurs legacy ou non maintenus, où « le code fait foi », donc je ne crée pas de ticket JIRA : je corrige directement au fil de la lecture.
    • Moi, j’utilise plutôt ceci :
      TODO: travail absolument nécessaire avant la release, exigence indispensable. Si ce n’est pas le cas, il faut le déplacer dans une autre catégorie. C’est bloquant pour la release
      FUTURE: pourra peut-être devenir un TODO un jour, généralement quelque chose d’optionnel comme de la conception structurelle
      MAYDO: ce serait bien de l’avoir, mais ce n’est pas indispensable
      PERF: à faire si davantage de performance devient nécessaire
      Et j’utilise aussi des tags sémantiques liés au domaine.
      À mon avis, les TODO ne sont pas un code smell ; ils s’accumulent naturellement dans les parties essentielles d’une codebase.
    • Moi, j’utilise XXX comme note personnelle pour dire « à corriger absolument avant la prochaine PR ».
      Si je veux être strict, je configure la CI pour rejeter tout code contenant cette chaîne.
      Dans ce sens, XXX est pour moi la priorité la plus élevée.
    • J’aime bien ce style. Sur un projet, on avait configuré la CI pour rejeter tout code contenant FIXME, et rejeter aussi les TODO sans ticket associé.
      Si on classe par ordre de priorité décroissant :
      FIXME: pour garder le focus. Doit être résolu avant de merger ou avant que le code soit considéré comme terminé
      XXX: à corriger bientôt. Ça fonctionne pour l’instant, mais il faut le corriger rapidement
      TODO: à revisiter plus tard. Le code est parfaitement utilisable. Priorité inférieure à XXX
      NOTE: explique des particularités ou des points à connaître pour aider les personnes qui passeront ensuite
    • Je fais à peu près pareil. Pour les chemins de code encore incomplets mais contournables, je mets un assert plutôt qu’un FIXME.
      TODO sert à laisser des pistes de travail possibles, comme du refactoring, de la performance ou des améliorations de clarté.
      NOTE sert à laisser du contexte historique ou un raisonnement qu’on ne comprendrait pas facilement au premier coup d’œil.
    • C’est bien en théorie, mais je pense que ce genre de convention n’a pas beaucoup de sens sans support outillé.
      Encore plus si on suppose qu’on travaille en équipe.
      Cela ne veut pas dire que l’idée n’a aucune valeur — simplement qu’il faudrait des outils pour cela, ou en créer.
  • Ça me rappelle le dicton selon lequel le mieux est l’ennemi du bien.
    Ce type de dette technique ou de code smell devrait en réalité être mieux suivi, documenté et expliqué, mais dès qu’on propose une tâche peu productive comme JIRA, on finit au contraire par ne plus rien noter du tout.
    Au moins, avec un TODO dans le code, l’information existe quelque part.
    Un TODO a aussi du sens parce que c’est bel et bien quelque chose « à faire ».
    • Dans une grosse codebase, les TODO de plusieurs personnes peuvent se mélanger et devenir compliqués, mais pour un projet perso, c’est un bon compromis.
      « Je sais qu’on pourrait mieux faire, mais je ne vais pas interrompre volontairement mon flow pour ça. La fonctionnalité n’est pas cassée, ce serait juste un petit plus. »
      Quand le surlignage TODO réapparaît parfois dans l’éditeur, ça aide à corriger rapidement une ou deux choses.
      Mais la plupart des TODO restent là pour toujours, ou en pratique ne sont presque jamais résolus.
    • Il m’arrive de laisser un TODO juste pour signaler dans le code qu’il y a quelque chose à traiter.
      Même si on l’enregistre dans JIRA, GH Issues, etc., il faut au final que le lien avec le code existe.
      Et si on ne laisse qu’une simple référence, elle peut perdre son sens plus tard ; il faut donc aussi une explication dans le commentaire.
    • Il existe déjà une fonctionnalité où un serveur MCP crée des tickets JIRA via l’IA et les exécute directement dans Cursor.
    • Je pense qu’il vaut bien mieux le mettre dans les messages de commit git.
      Beaucoup de commits ne transmettent en réalité pas bien leur contenu.
      Au lieu d’encourager la vieille habitude des TODO, j’aimerais qu’on pousse à utiliser de meilleurs outils.
      Beaucoup de développeurs committent trop rarement et regroupent plusieurs travaux d’un coup.
      Et les messages de commit sont souvent aussi vides de sens que « updating somefile.py ».
  • C’est une question de style. Chacun peut avoir sa propre définition ou sa propre culture autour des TODO.
    Dans ma codebase, TODO est utilisé comme décrit ici.
    TODO sert à documenter l’implémentation, en particulier ce qui manque — pas forcément à indiquer quelque chose qu’il faut absolument traiter.
    À mon avis, laisser une vraie liste de tâches directement dans le code n’a pas beaucoup de sens. Les priorités changent sans arrêt : quelque chose pouvait sembler important au moment de l’écrire, puis ne plus l’être, tandis qu’un autre problème non anticipé peut devenir plus urgent plus tard.
    On ne va pas soumettre des PR en permanence juste pour mettre à jour des commentaires TODO.
    Si vous voulez tenir une liste de choses à faire, mieux vaut la gérer à l’extérieur, dans un issue tracker ou dans un document texte facile à mettre à jour.
  • Le titre est un peu putaclic, mais je suis entièrement d’accord avec le fond.
    Je viens justement d’ajouter un #TODO pour signaler un cas exceptionnel extrêmement rare. Ça ne s’est jamais produit en deux ans, mais ça m’aidera plus tard si je me demande pourquoi je n’ai pas traité cette partie.
    Je comprends aussi ceux qui disent que ce genre de chose devrait simplement être laissé en commentaire. Cela dépend de la nature de la codebase, et dans un contexte comme le mien, avec une équipe de deux personnes, l’approche TODO marche bien.
    • Dans notre équipe, on utilisait // TBD: [...] pour cet usage. C’était une petite ruse pour que les personnes obsédées par les TODO ne le remarquent pas.
  • Il faut un endroit pour noter les problèmes connus qui ont de la valeur mais ne nécessitent pas forcément de suivi.
    On ne prévoit pas réellement de les corriger, mais un jour, s’il y a du temps, on pourra avoir envie de faire un ctrl-F pour voir s’il y avait quelque chose à nettoyer.
    Je trouve déraisonnable que trop d’outils ou de processus considèrent les TODO comme un code smell.
    • Personnellement, je n’ai encore jamais vraiment rencontré ce type de problème.
      Pour moi, ce n’est qu’une question de priorité ; au fond, c’est une vitre brisée (la métaphore bien connue de Pragmatic Programmer).
      Si on a réellement décidé de ne jamais corriger quelque chose, il vaut mieux le documenter dans la documentation logicielle.
  • Dans l’exemple donné dans l’article :

    // TODO: If the user triple-clicks this button, the click handler errors because [xyz]
    pour moi, ce n’est pas vraiment un TODO, mais plutôt un simple commentaire.
    Ce genre de commentaire explicatif est clairement utile, mais l’appeler TODO est discutable.
    Un TODO devrait désigner un vrai élément à traiter, quelque chose qui doit changer, comme « cette fonction devrait renvoyer une valeur différente selon XYZ ».
    Dans ce sens, un TODO ne devrait pas être enfoui dans le code, mais figurer dans un issue tracker.
    D’après mon expérience, les TODO servent surtout à justifier un sacrifice de qualité du code pour obtenir plus vite l’approbation d’une PR. En pratique, ils sont rarement exécutés, et ne laissent que l’idée vague que « le développeur junior qui aura du temps s’en occupera un jour ».

    • Un commentaire sert à expliquer pourquoi ce code se comporte de cette façon.
      Par exemple, si on écrit simplement
      // If the user triple-clicks this button, the click handler errors because [xyz]
      on ne sait pas clairement s’il s’agit d’un bug ou d’un comportement voulu.
      TODO est juste un signal simple pour dire « il y a ici quelque chose d’imparfait ; gardez-le en tête quand vous travaillez dessus ».
      Si c’est vraiment quelque chose qu’il faut obligatoirement résoudre, alors oui, il faut le suivre ailleurs.
      Mais si on réduit trop les TODO, on risque surtout d’augmenter la quantité de code non documenté.
    • Je ne trouve pas que l’exemple cité soit un bon TODO.
      À ce stade, autant corriger directement le bug, ou laisser un commentaire du genre « le triple-clic est ignoré à cause de [xyz] ».
      Si on a déjà identifié le déclencheur et la cause, j’ai l’impression que 80 % du travail est déjà fait.
    • Je vois ça plutôt comme un « à sauter ». Dans bien des cas, on peut très bien ne jamais s’en occuper.
      Le vrai problème, c’est quand on suppose que le code fonctionne parfaitement alors que ce n’est pas le cas.
      Le meilleur TODO que j’aie vu était quelque chose comme « TODO: encrypt this » dans du code de sécurité.
      Grâce à ça, il était immédiatement évident pour tout le monde que cette partie n’était pas chiffrée, et cela évitait aussi de se demander si le chiffrement était géré ailleurs par modularisation, ou s’il y avait un risque de double chiffrement.
    • L’exemple donné ressemble plus à un FIXME qu’à un TODO.
      C’est clairement une erreur, mais pas forcément quelque chose qu’il soit très important de traiter.
  • Je suis fermement opposé à ça.
    Si vous n’allez pas l’enregistrer comme bug ni vraiment travailler dessus, je préférerais qu’on ne laisse pas de TODO.
    // TODO: If the user triple-clicks this button, the click handler errors because [xyz]
    Ici, on ne fait que consigner un symptôme. Le mot TODO ne devrait pas être là.
  • Moi aussi, je les utilise de manière hiérarchique.
    FIXME quand il faut absolument corriger quelque chose, ou quand l’étape suivante est évidente.
    TODO pour des idées plus vagues, ou simplement pour sortir quelque chose de ma tête et me reconcentrer sur autre chose.
    Cela couvre beaucoup de cas : l’idée n’est pas encore mûre, je ne suis pas certain qu’il faille vraiment le faire, ou bien j’attends quelque chose de lié.
    Si je ne le note pas, ça continue à me trotter dans la tête ; alors que dès que je l’écris, TODO ou autre, je me sens beaucoup plus léger.
  • Je vois les commentaires comme le signe qu’on n’a pas su écrire un code assez clair.
    J’aimerais pouvoir écrire du code compréhensible immédiatement, sans commentaire.
    Mais si c’est tellement confus que même moi je ne le comprendrai plus plus tard, je finis quand même par écrire un commentaire.
    Ce qui est triste, c’est que si quelqu’un modifie ensuite le code sans mettre à jour le commentaire, cela ne fait qu’ajouter de la confusion.
    À mon avis, les TODO ne devraient pas se trouver dans du code commité, mais être gérés dans le projet ou dans un système de gestion de tickets.