10 ms·

TODOs aren't for doing

413 points by todsacerdoti 1y ago

AnotherGoodName 1y ago
Fwiw i’ve see far fewer todos lately since LLMs have gotten significantly better as of late. The todo documentation is often a perfect prompt.
newswasboring 1y ago
Off topic, but this is such a great blog format. Encourages writing small things just by how it looks. I would love to make my own blog like this, does anyone know how this was done?
- CRConrad 1y ago
  Presumably https://news.ycombinator.com/user?id=sophiebits https://news.ycombinator.com/user?id=sophiebits , who commented twice in this discussion, would know.
it_citizen 1y ago
Then maybe those todos are not todos but just regular comments?
- happytoexplain 1y ago
  Then they would be lost. Comments are for understanding how something works. TODOs are for understanding how something might not work. Edit: And if you put them in a tracker, they'd be distracting and confusing for team members less intimately familiar with the codebase, e.g. a PO. You could also choose a word other than "TODO", as long as it won't produce a ton of false positives in a search.
  - dorian-graph 1y ago
    What does it mean to be lost? Why would a TODO comment not be lost, versus a comment without that prefix?
  - marcosdumay 1y ago
    If you put them in a tracker, soon enough there will be somebody asking why 90% of the issues are not being worked on, will complain if they just disappear one day, and will disappear for political reasons.
  - jraph 1y ago
    > Comments are for understanding how something works Even better: for understanding why some code does this surprising or seemingly complicated thing it's doing
happytoexplain 1y ago
Agreed - there needs to be a space for known issues that are not worth tracking. Issues that need to be understood as real, but perhaps may never be viable to fix. Something you can ctrl-F for when you have time and are curious if there's something you can clean up. It drives me insane that so many tools/processes treat TODOs as essentially code smells.
- skydhash 1y ago
  I still have to come across one of those issues. It may not be a priority, but it is a broken window (Pragmatic Programmer book). If it’s a won’t fix type of issue, just add it to the software docs.
- KolibriFly 1y ago
  Not every TODO is technical debt waiting to be paid off
mcntsh 1y ago
To me this brings the phrase to mind: "perfect is the enemy of the good." Ideally tech debt or code-smell encountered like this would be captured/tracked/described better but often-times this means context switching or engaging in some kind of high-friction activity (like filling out a JIRA ticket) and that just discourages tracking it at all. At least inline TODOs are captured somewhere. And they can be for doing.
- sublinear 1y ago
  Put it in your git commit message. Most commits people make are rather bad. Instead of taking us back to the stone age with TODOs, why not encourage better tool usage? Many don't commit often enough and instead tangle together unrelated changes. The cherry on top is when the commit message is just "updating somefile.py" or something similarly unhelpful.
  - mcntsh 1y ago
    How would that be discovered? If I inline a TODO comment calling out some tech-debt that I (we, our team) had to take on, then in the future when the next person touches that logic they will see that comment and might address it. If it's in a commit message it might as well be invisible.
    - sublinear 1y ago
      Discovered by other devs? git blame. Discovered by the rest of your org? I don't see how a TODO in the code is more visible than a git commit message. In fact, at least it's possible that non-devs may still be able to see the git commit messages in a feed or have read access to repos.
      - mcntsh 1y ago
        Instead of relying on people actively checking the git-blame for all of the code they're reading, why not just put a clearly obvious comment within the code itself?
sublinear 1y ago
TODOs are a code smell. If there's a known unhandled edge case there should be conditional logic guarding against it. If the original author dislikes the idea of a refactor... well too bad it's not their decision anymore, but they should have at least been kind enough to write tests.
- happytoexplain 1y ago
  This is unrealistic, or possibly you just haven't used platforms/languages that benefit from a layer of record-keeping lower than is appropriate for a ticket-tracking system. Also, a TODO doesn't mean you have not guarded against an edge case. A TODO could be anything that increases the health of the codebase or application. You can guard against an edge case, and then write a TODO on that guard that mentions that you'd like to recover from the edge case, rather than simply guard it.
  - zahlman 1y ago
    >This is unrealistic While I don't necessarily agree with GP, this isn't a refutation. Yes, eliminating code smells entirely is, in typical development environments for sufficiently large projects, entirely unrealistic. That doesn't make them not smells.
- ebiester 1y ago
  Sometimes, it's "there is something wrong here but I cannot figure out a way to make it better yet without working nights and weekends for the next three months with no benefit to myself."
- blitzar 1y ago
  There is always an unhandled edge case
- gabrielhidasy 1y ago
  TODO: Remove the 'FillInData' function call after bug/<id> is fixed.
ipince 1y ago
But the second example there shouldn't be a TODO then, but just a NOTE (or regular comment).
basfo 1y ago
The example in the article: > // TODO: If the user triple-clicks this button, the click handler errors because [xyz] looks more like a comment than a real TODO to me. I agree that comments like those are useful, but shouldn't be a TODO. A TODO implies a specific type of comment. One that implies a task, points to something that should actually be done (like TODO: This function should return another value with XYZ). And I agree that the proper place for that is a tracker, not buried in the code. In the example just documents a bug. , there is no actual action. In my experience, TODOs are often a way to get quick and dirty code approved in a PR. They usually never get done, they're just a way to push the responsibility onto some future developer who "will have more time" (which means it will likely never happen).
- sophiebits 1y ago
  Comments are usually for explaining why code is doing what it’s doing. If you write just // If the user triple-clicks this button, the click handler errors because [xyz] then it’s less clear at a glance that this behavior is undesirable. Is this a bug, or is it supposed to be this way? “TODO” is a quick marker that (to me) means “here’s something that is not ideal and may be worth keeping in mind if you are working on this code”. If you or your reviewers know that it’s not OK for the fix to never be implemented, then of course, track it somewhere where it will get done. My experience is that discouraging TODO comments leads to less-documented code, not better code.
  - kstrauser 1y ago
    I think that's a case for "NOTE", which has the semantics of "this is something unusual and significant to pay attention to". Edit: BTW, my specific disagreement is with using "TODO" to mean different things. I'm otherwise completely on board with the kinds of comments you're asking people to write, even if I'd label them differently. When I'm trying to understand new code, much of the effort is in trying to figure out why the author chose the approach they did. Why'd they do this instead of the more usual approach? Did they understand the tradeoffs, or just find things on Stack Overflow or ChatGPT? Did they take this edge case into consideration? Seeing their thinking is vastly more useful than // Add two numbers three = one + two
TOGoS 1y ago
When I have a thought about how some piece of code could/should be improved, but it's not urgent, instead of // TODO: Refactor this by doing X, Y, Z I'll say // Hmm: This seems brittle. We might want to X, Y, Z this such that W. My IDE will list all the TODOs and I don't like to clutter that list with stuff that isn't strictly necessary, but it is nice to have some string--"Hmm:", in this case--that I can grep for or recognize as indicating that I thought about this already.
singron 1y ago
I have a similar philosophy for low priority tickets. Some people say it's not worth filing a low priority ticket since we can't even do the medium priority ones. I think it's still valuable since (1) it let's you write it down to remove it from your mind, and (2) you can track repeated instances or anything else that might cause you to increase the priority.
pisipisipisi 1y ago
I add and grep for the following: - FIXME: this is clearly broken/wrong and highest priority - XXX: this is “ugly” or assumes wrong things, probably higher than next - TODO: at some point, implement a whole different approach/category/branch - NOTE: code comment with a higher importance than just random comment NOTE: I work a lot with old/unmaintained codebases where “code is truth”, so there is no “jira ticket creation” but amending things as you read.
- radlad 1y ago
  This is pretty much what I do too. `XXX` is "Look here! This is important!" or "You might not expect this!" I rarely use NOTE, but I have on occasion.
  - jackpirate 1y ago
    What's the origin of XXX? I've seen FIXME/NOTE/TODO all over the place, but never encountered XXX before.
    - pisipisipisi 1y ago
      Amsterdam.
    - slongfield 1y ago
      It has some ancient history as a morse code distress signal: https://regulatorylibrary.caa.co.uk/923-2012/Content/Regs/03800_1._DISTRESS_AND_URGENCY_SIGNALS.htm https://regulatorylibrary.caa.co.uk/923-2012/Content/Regs/03... And it shows up in some old BSD code: https://www.snellman.net/blog/archive/2017-04-17-xxx-fixme/ https://www.snellman.net/blog/archive/2017-04-17-xxx-fixme/ But... I think repeated letters are just easier to type than any other string, and since X looks like the classic "marks the spot" logo, it's what people jump to.
    - 1659447091 1y ago
      I always thought it was from Java, but that's probably a personal bias; I am sure it was used long before Java was a thing. I did find this though (archived from 1999): https://www.oracle.com/java/technologies/javase/codeconventions-programmingpractices.html#395 https://www.oracle.com/java/technologies/javase/codeconventi...
titzer 1y ago
I have three levels: 1. An issue tracker, even if it's just a text file for some projects. These are things that need to get done over the long term. 2. TODOs. These are actually bugs or incomplete things. The code is not actually done. Something isn't handled, something isn't right. Big or small, but usually small. 3. XXXs. These are performance enhancements or refactorings. It's XXX because it's obscene that this code looks this way, because it's either ugly, slow, or gross. But the code works and is tested.
pkilgore 1y ago
My whole thing here is that this is just as effective of a comment without the todo prefix. Lint the TODO part before merging, then TODO becomes a nice thing you can grep for on your own branch, like a note to yourself.
nevermore 1y ago
As a proponent of "TODOs should always point to a concrete issue", you have 3 ways to resolve a TODO before merging: 1. Just file the issue. If it's something you should actually do, you can take 20 seconds to write it down and track it. 2. Just do it. If it seems like too small of a thing to file an issue for, fix it before you commit it. 3. Turn it into a comment. If it's not worth fixing and not worth tracking, but you want to remember it, that's a fine thing for a regular code comment. Eat your broccoli. Track your todos.
- mcntsh 1y ago
  I wish tracking took 20 seconds. In my org (big tech) a JIRA ticket has 10+ required fields.
  - hinkley 1y ago
    Jira is awful because it has no opinions and leaves those decisions up to people who have terrible ones.
    - indoordin0saur 1y ago
      Jira really seems to have degraded as it has become increasingly bloated. I grit my teeth every time I hear platform ops say "hey, that deployment ticket last week... we noticed you didn't fill out the x, and z fields and also didn't create a follow-up ticket for future deployment to prod with the correct link to the implementation ticket"
      - maccard 1y ago
        That’s nothing to do with jira and everything to do with your platform ops team.
        hinkley 1y ago
        That’s only true if you think the person who made the torture device is not culpable for their customers using it as a torture device. I don’t happen to believe that is true. Pandering to customers makes you part of the problem.
baalimago 1y ago
// TODO(<issue-tracker-id>): <Short description> This format allow for quickly finding the place where the thing needs to be done, while keeping track of the issue in the issue tracker. I often write the issue tracker ID's in my code to add additional context. It works especially well for bugs which are reproducable in programatic tests. Then I name the test specification after the ticket, so that it's known that this bug doesn't resurface as regression.
allthedatas 1y ago
I also use a tiered strategy and FIXME for things that really need to be fixed or I have a solid idea what the next step would be to fixing it. TODOs are something less solid than a FIXME and are also just about getting it out of your head so you can devote more mental energy to something else or just relax. Maybe the idea is not fully formed yet, maybe you are not sure you really want to do it, maybe it is waiting on something else, but it needs to be captured or you will have to keep thinking about it lest you forget. As soon as I write down a TODO (code or other) that was only in my head, I can relax a little more, because now it's captured for future reference.
lmc 1y ago
In my code these days, I have: TODO SHOULDDO COULDDO The TODOs generally don't make it to main, the others sometimes get picked up eventually.
- ivanjermakov 1y ago
  I think common terminology for there are FIXME, TODO, XXX in that order, but YMMV
- jffhn 1y ago
  I only use "TODO" eventually followed by a sub-classification like "TODO bug": it maximizes discoverability by other devs and tools, and allows for a lot of variants (both technical and/or functional) while still permitting a complete scan with a single grep.
kstrauser 1y ago
I couldn't disagree more. TODO is basically an action list you search with grep. When I'm looking for things that could be done, the last thing I want to do is to have to mentally filter out the things that aren't actionable. That just makes the process use a lot more mental energy than necessary. It also leads to unproductive conversations like "we have 147 TODOs, but 18 of them actually need doing at some point, which is an improvement from last month's 123 TODOs with 22 real ones". No, please, do not do this. As notes, those are wonderful things to add. They're the sort of comments I want to see in the code I'm reading! Keep them! But don't label them as TODOs, for the same reasons that you wouldn't use Reminders as your combined actions and notes app. Edit: In addition to the mental energy, your brain eventually gives up and becomes blind to them. Then you tend not to see them at all, even the actionable ones, unless you step back and dedicate even more mental energy to mindfully going through them one at a time to give them a fair reassessment. This gives me more ADHD-fueled anxiety than I can describe.
- muzani 1y ago
  "your brain eventually gives up and becomes blind to them." This is not a bad thing if they are not for doing. They're there to mark that the code is incomplete but not broken. The actual to do is a FIXME.
  - kstrauser 1y ago
    It's a bad thing if you're using the same tag for "we need to change this" and "this is something we might eventually consider". Imagine looking in your bug tracker and seeing a thousand tasks with no differentiation, no tagging, no priority marking, and trying to decide what to do next. Only things that are genuinely actionable should be marked as actions to be done. If it's just something you'd like to clean up, eventually, given infinite free time, label it as a note. Otherwise you're blowing up the amount of information you have to sift through when deciding what work to do.
    - sfink 1y ago
      I'm not sure you're disagreeing with the post you're replying to? I tend to use FIXME for things that really do need to be fixed, and will not push code containing a FIXME comment. Grepping for FIXME is useful. I tend to use TODO for things that I'm thinking may be useful, but aren't necessary (yet). Sometimes it'll be "TODO: Figure out whether..." or "TODO: Validate this by measuring the impact, to see if it'd be better to do something more complicated or simpler." I could rewrite all of these as regular comments -- the latter might be "I have not validated the assumptions here via measurements; something simpler might be good enough." But the TODO is a little more direct. Grepping my code for TODO isn't that useful. (Well, save for the comment block at the top, where I tend to leave actual todo comments, but they're still future tasks not FIXME-style "do this before landing" tasks. And I label them with [ ] checkboxes, not "TODO".) So we agree: don't use the same tag for both. It sounds like you use TODO for "we need to change this" and I use FIXME for that. I suspect we all have a broad range of labels: TODO, FIXME, NOTE, plain comments, comments linked to bugs, etc. When reviewing teammates' code, I check whether their TODO comments should have a bug link, should not say "TODO", should be removed entirely, or whatever.
ivanjermakov 1y ago
I have never seen TODOs being cleaned up in enterprise environment. Therefore our team would not approve PR with TODOs: either fix them yourself or open a separate ticket for it.
- dboreham 1y ago
  There's no back-link mechanism for a ticket. If there were (when viewing the code there's some visual queue that there's a todo ticket open for this line) then I'd agree. Also consider the infuriating practice where managers (often with the help of supercilious bots) close tickets "just because".
  - CRConrad 1y ago
    > There's no back-link mechanism for a ticket. Of course there is: Put the ticket number (or URL) in a comment.
dkarl 1y ago
This is a great example of a practice that is pragmatic and smooths the way for future polish if the software grows in usage by 100x, without investing a bunch of effort now that won't make sense if it doesn't grow (and might stop you from doing the things that will enable it to grow.) If usage takes off by 100x, someday somebody will be tasked with clearing up errors in Sentry (or whatever) so bugs and regressions are easier to spot, and this comment will save them hours of debugging. However, I think using TODO to flag it is a poor choice. Good luck explaining to your teammates, "We use TODO to communicate that we aren't going to do something." I doubt you're going to get consistent adherence to such a counterintuitive convention. Instead, I would prefix the comment with "KNOWN ISSUE."
owlstuffing 1y ago
Replace the not-TODOs with NOTEs. For example, this TODO: //todo: factor this out in case X …is a NOTE, albeit a gratuitous one. Because if X ever happens, the note won’t matter anyway, since you will have had to grok all the related code to refactor. You will see this note while you’re refactoring the surrounding code and smirk, “yep, that’s right”, or “no, it doesn’t really fall out that way.” Either way, most TODOs/NOTEs like this just get in the way.
- zahlman 1y ago
  To me, "NOTE" still implies that the comment is about describing the existing state, rather than a desired future state.
kamens 1y ago
I love this TODO approach not just for what it does for future readers as Sophie notes but also for the mental release it gives me when thinking about edge cases that I don't want to commit to fixing. PS Hi Sophie!
- sophiebits 1y ago
  Hi!
gblargg 1y ago
They capture information you have when writing the code that communicates something useful about it.
ngruhn 1y ago
Strongly agree. I think of TODO as a task that might be interesting for the next person who stumbles over this code. "This logic is not great. If you happen to refactor this entire feature consider changing this thing as well". The TODO can even have an associated ticket but because it's right in the code it's more discoverable. Otherwise, the next person to change the code might even complete the ticket without knowing it.
- paulddraper 1y ago
  "Ideally, this code would X. It's acceptable that it doesn't, but if you do change it, considering doing this differently."
- luckydata 1y ago
  then it's not a TODO, it's just part of the comments. Promoting semantic diffusion IMHO is not a good practice in software development.
  - paulddraper 1y ago
    How would you quickly identify something as "would be better if." It's a "to do" but on a long (perhaps indefinite) timeframe.
    - CRConrad 1y ago
      > How would you quickly identify something as "would be better if." [? -- my addition // CRC] How about by writing a comment containing the words "would be better if"?
tonnydourado 1y ago
Second todo isn't a todo, should be a trade-off comment. Something like "Technically, this will raise an error if the user triple clicks the button, but most people ain't that fast, so screw it"
rglover 1y ago
This is just going to lead to things not being done as nobody knows whether or not the TODO is resolved or not. Personally, I tag my comments in one of two ways: 1. // TODO: <task> (if multiple things, I do a multiline comment with Markdown-style checkboxes next to each item in the list). 2. // NOTE: <explainer> The former is what you'd expect (I routinely search for these to make sure I'm not missing minutiae) and the latter is for code that can't be refactored to make it clear and requires some explanation. Doing this consistently has really saved my bacon over the years (both in terms of keeping track of tasks and remembering why I had to use that ridiculous chunk of code to get something to work).
x______________ 1y ago
Off topic, what did the detective say to the developer? TODO, TODO, TODO TODO TODO TODO TODOOOOO ...No? Ok fine, how do you track completed TODOs? With TADAs! Ok fine, I'll show myself out. // TODO: Find better material
deadbabe 1y ago
If your TODO isn’t actionable, I’m deleting it. Too bad. Bury your skeletons elsewhere.
CivBase 1y ago
> But the `// TODO:` doesn’t need to be a plan to actually do something. Instead, it’s a note about “here’s an edge case that wasn’t handled” or a suggestion for a better structure that the author didn’t make time to implement — it captures a little slice of the author’s brain and gives a little window into the rich context they had at the time they wrote the code. Sounds to me like this should just be a regular comment. Don't add "TODO" if you're not actually going TO DO it.
malkosta 1y ago
If it's not intended to be done, then you are using the wrong name. Don't call it `TODO`.
- indoordin0saur 1y ago
  Sometimes "TODO" means something you would do if you had infinite time, refactor the code completely or something that will likely need to be revisited in the future but currently adds no value to implement.
  - malkosta 1y ago
    TODO is a pretty clear name. If it's not to be done, then it should be just a regular comment, no need to tag as TODO.
Tokumei-no-hito 1y ago
OP, have a look at todo tree: https://github.com/Gruntfuggly/todo-tree https://github.com/Gruntfuggly/todo-tree it's a game changer while solo or on a team. and I’m sure it's reproducible outside of vscode (it's just highlighting depending on the todo token used). been using it and introducing it to teams for years. it's even more helpful now with AI.
gabrielhidasy 1y ago
What? What's 'TODO' about the second TODO in the article? >> // TODO: If the user triple-clicks this button, the click handler errors because [xyz] That could be a simple comment, but if its a TODO it should be ´TODO(bug/<id>): Fix triple-click error in this button´. If you really want to tag a normal comment, what about // NOTE?
luckydata 1y ago
I rarely find reasons to disagree so much with anything I read like I did with this blog post. Seems like the author lacks rigor and then goes looking for ways to excuse being sloppy, that's an attitude I don't think is productive or creates anything positive in the industry.
OutOfHere 1y ago
If a TODO is not for doing, it should be recorded as a NOTE, documenting the limitation instead of the task.
escobar_west 1y ago
This article should expand more on what TODOs are actually for, in that case. What's the difference between a regular comment (which is what the example in the article clearly is) vs an actual TODO comment?
pamelafox 1y ago
My personal philosophy is that TODOs should only be used while working on a branch. Once its ready for a pull request, any pending TODOs should be abandoned or logged in an issue tracker.
morsecodist 1y ago
I think this is fair. Untracked TODOs should be minimized but I think there is value in recording how some section of code could be improved even if you know you are unlikely to do it. I don't think the triple click thing is a good example because that seems like a bug to me. An example from my codebase is that I implemented a daily scheduled job that may display inconsistent results during short time per day it is running. Realistically fixing this will never be worth my time, this is a transit app and it is scheduled to do this at night when the buses aren't running and it will only be inconsistent if they change the schedule after already publishing it for a given day which happens pretty much never. It is also a personal project with no issue tracking. Eventually I will rewrite this loader logic to support multiple transit systems so it is good to have my notes of how I would do it better next time. Also, if this does result strange schedule behavior I would immediately go to this file and see my explanation of the flaws with my approach. Maybe I shouldn't call this a TODO but it seems like a good fit.
kentonv 1y ago
This is a style issue. Different people can have different definitions and cultures around TODOs. My codebases tend to use TODO exactly as described here. A TODO is really just a comment documenting the implementation -- specifically, documenting something that is missing, but could be useful. It doesn't mean it actually needs to be done. IMO it doesn't make sense to use comments in the codebase itself as an actual task list, because priorities are constantly changing. Things that seemed important when you wrote the code may turn out not to be, and things that you didn't think of when writing turn out to be needed. Are you constantly submitting PRs just to update the TODO comments to reflect current thinking? I mean, sure, I guess you could do that, but I think it makes more sense to maintain that list in a bug tracker or even just a text document that can be updated with less overhead.
metalrain 1y ago
I think TODOs are great for refactors you cannot start right now. It's very local, this code should change but it might not be possible during the timeframe I've been given. For future reader it might give hint what to change or what is wrong here.
Arainach 1y ago
Hard disagree. If you're not going to file a bug or ever do it, don't write TODO // TODO: If the user triple-clicks this button, the click handler errors because [xyz] This is documenting what currently happens. It's not TODO, and that word shouldn't be in the comment.
- kaashif 1y ago
  Yeah, TODOs should start with a verb which tells you to, you know, DO something.
thenoblesunfish 1y ago
It seems pointless to write "TODO" if it's not, you know, to do. Yes you should write comments describing ways the code can be inproved, but those can just be comments that don't confuse other people, not to mention trip all sorts of code highlighting and automated checks.
phtrivier 1y ago
I've certainly overdone it. When I left a job after many years, my collegues printed a listing of all my // TODO(pht) . It was big and full of things that never got "TODONE".
deleted 1y ago
[deleted]
owlbite 1y ago
My policy: If it's a real TODO, it includes the ticket number/link tracking the actual fix. Otherwise it should either be a regular comment or not exist.
fellowniusmonk 1y ago
TODO: Action item that must get done at some point. TODO? or ?TODO: Documenting funky code that the developer can't triage at the moment without losing flow state but is "off". Instead of a separate MAYBE any action should have an indicator of confidence level. We are marking the developers intuition about something they have run into, human intuition is both important and fuzzy, we should mark it as such. The more ? the fuzzier it gets. Humans have a bunch of symbols in their brains, we may disagree about the symbols usage but if a developer has a small thought about a codebase let them get it out quickly and with clarity. The real problem is that unified tooling for plaintext editing and zoomed out team project management don't have a good interface that let's people notate with the level of friction commiserate to the importance of the notation.
perfmode 1y ago
For cases like the one described in the article, I prefer NB comments. // NB: If the user triple-clicks this button, the click handler errors because [xyz]
- rustyminnow 1y ago
  What does NB stand for? Edit: "Nota bene" apparently: https://en.wikipedia.org/wiki/Nota_bene https://en.wikipedia.org/wiki/Nota_bene
nektro 1y ago
great post
dgunay 1y ago
I think there are lots of valid ways of using TODO comments. In my org, TODO comments trigger the linter, so they usually have to be addressed, downgraded to a regular comment, or turned into a ticket. They're a nice way for me to mark places I need to remember to come back to before I put something up for review. I sympathize heavily with the viewpoint that pushing these things into ticketing systems means they're less likely to get done. I think it's nearly impossible to lobby for TODO: comments to get done against a never ending stream of ultra important high business value work. Leaving these concerns inside of the codebase itself is one way that programmers can take back control when technical concerns and code quality are dismissed or deprioritized constantly.
0x457 1y ago
Interesting, yesterday I was looking at the source code of some library, and noticed a lot TODOs scattered all over. At first, I thought it's a red flag and I shouldn't use this library. However, once I read them all of them, were exactly this: very rare edge cases, minor optimizations, and notes about future optimizations possible optimizations. I pretty much immediately adopted this style of todos.
pkghost 1y ago
for the laconic and latin-leaning, NB (nota bene) means "note well"
indoordin0saur 1y ago
Title is a little click-baity but I fully agree with the sentiment. Just minutes ago I had this experience where a #TODO marked out some extremely rare edge case to handle but one that I have never seen actually occur in the 2 years since I put it in there. Still it will be useful to others (and future me) when I look back at the code and wonder why something wasn't handled. I also agree with users that sometimes these should just be comments. Really depends on your environment and since I work on a team of 2 who maintain my portion of the codebase I stick with using TODOs in this way (seomtimes).
- MathMonkeyMan 1y ago
  I was on a team that used `// TBD: [...]` for this purpose, so that the "TODO people" wouldn't notice.
  - CRConrad 1y ago
    Add to that: // PBD: Possibly be done...? // NBD: Not being done! And, Idunno, perhaps some more.
almosthere 1y ago
Introducing TODO.ai where we handle all your todos for you
joaomeloplus 1y ago
I see comments as a failure of my prose capacity at coding. I try to commit code that should be able to explain itself as if it were accompanied by any comments. But if something is too confusing to be maintained by someone else (like me 6 months from now), then I use a comment. But that is a sad moment because I also know that this future person can update the code and not update the comment, then the thing becomes even more confusing. TODOs should never be in committed code; they should live in your project/issue management system.
Detrytus 1y ago
I think some of the TODOs are used to silence programmer's guilty conscience and protect their reputation in the eyes of future maintainer (which might be their colleague): "I know this code sucks, and this is how it can be made better, it's just my PM was pushing me to finish this task ASAP"
pkghost 1y ago
for the laconic and latin-familiar, NB stands for nota bene, or "note well".
bilekas 1y ago
Maybe I'm strange but I'll throw TODO In my code as I'm working through it, usually alone the lines of "double check the chain here later" When I'm then doing my final commit I'll do a search and check them off.. Theyre incredibly useful. I use pen and paper too but they go missing
FpUser 1y ago
I have 2 kinds of TODOs in my code: // TODO: optimize something, refactor, blah ... // TO_F_DO: this thing is gonna blow up, can't fix it now but do it ASAP TODO - when I have nothing to do I browse those, pick the on I like and do it. TO_F_DO - if I find more than 1 in my code I am suicidal
cadamsdotcom 1y ago
For that reason I’ll often prefer the word REVISIT instead of TODO. Kinda less obligatory.
bippihippi1 1y ago
sometimes I use todod for regex search and replace to refactor later. like to mark all the places where I want to later change the logging level, but for now I want to info log the query headers.
ShadowBanThis03 1y ago
WTF is "TODO?" Step one is: learn English.
laserbeam 1y ago
This short article is not about TODOs, it’s about good comments, in general. Any comment that gives you context about edge cases, about why some decision was made, about why other approaches went wrong is great! I would argue TODO means “intent to implement”, and they should be regularly converted into either tasks, documentation or just standard comments without a special keyword.
bambax 1y ago
> Ehh, maybe I’ll just leave it the way it was in case the original author knew something I don’t. That's probably the main point of code comments in general: to explain to the future reader or maintener (who may be your future self) why things are the way they are.
KolibriFly 1y ago
TODO's sometimes just a breadcrumb for future devs (or your future self) to understand the why behind a weird decision or an unhandled edge case
bravesoul2 1y ago
It is noise and correctness of the TODO needs to be maintained over code changes. Todos IMO should be limited to branches but not merged to trunk.
azangru 1y ago
> But the // TODO: doesn’t need to be a plan to actually do something. Instead, it’s a note about “here’s an edge case that wasn’t handled” or a suggestion for a better structure that the author didn’t make time to implement Why is it a TODO, and not a NOTE or something?
voidUpdate 1y ago
To me, TODO is something that I need to do. For example, I recently did a large refactor on a codebase, and commented out some large function blocks, just so it would compile and run properly, just with some functionality missing, but I left a TODO saying that I needed to actually implement them so I could find the blocks again. TODO is something you need to do, not just a remark about the code
ahoka 1y ago
TODOs are rain checks on technical debt. They are perfectly fine, leave them alone!
stephenhandley 1y ago
Effective TODOs capture a code-level design tradeoff and any associated debt which - won't have sufficient positive impact on the bug/feature you are working on - you don't have time to address at that point in time - are significant enough to require pay down later How to address them in terms of tooling and process is a way bigger question
- alex-moon 1y ago
  I think this is a really good way to think of it actually. My business partner and I often have this back and forth: "Do you want this done the right way or the fast way?" Most often we do a "happy medium" between the two and accept that there is work to be done in the future. This is not a bad way to do it, as more often than not the "right way" actually needs quite a bit more customer research first - often pushing "Todo" code to production reveals the use cases that show that the suspected "right way" was wrong, and the actual "right way" is to burn all the code and use a completely different existing module to do it instead, consolidating what were (incorrectly) understood to be different use cases. This is probably my favourite way of paying down technical debt.
damnever 1y ago
I think we should better differentiate between HACK and NOTE from TODOs.
cjfd 1y ago
Well, if TODOs are not for doing, how about just not putting 'TODO' in front of them? Maybe we could sometimes attempt to use words to stand for what they actually mean. Could that possibly be helpful for peoples understanding? Also, the first and most important place for putting TODO's is the issue tracking system so I think in most cases they do not have to be in the code. I might allow them occasionally if they refer an issue in the issue tracking system. Another use of TODO comments that is not necessarily bad is if you yourself or someone else is supposed to resolve all of them before the relevant code is merged into mainline.
MaulingMonkey 1y ago
Externally visible issue where external parties (producers, co-developers, artists, designers, ...) need communication about fixes and timelines? Put it in the issue tracker so people can subscribe, elaborate on repro steps, share links so QA can learn how to verify it's broken / fixed, etc. Something that needs to be fixed in your local changes before committing, lest something break terribly? Put it in code in such a way that your CI system will reject integration. That can be a // TODO or // DO_NOT_COMMIT comment that can be recognized and rejected by your git pre-commit hooks. Perforce lets you stage and describe changelists before committing them, and you can make hooks that will reject TODOs in those descriptions as well. In a pinch, #ifdefs to check for CI and a static_assert(false, ...); might be another option. One of my more common uses of this pattern is when extending or refactoring a platform abstraction layer - it tends to be easier to get it working on one platform first, and forgetting to test it on a second platform can be very easy. Switching contexts to an external issue tracker for things that nobody but yourself will ever read isn't adding value - keeping it in code where you can build safeguards that will literally prevent you from doing the wrong thing by accident will. Internal refactoring or performance improvement suggestions? Those often go in the non-blocking non-tracker // TODO bucket for me. They can safely rot away unnoticed for 10 years without causing problems as issue trackers come and go, then suddenly become relevant as new needs cause new development, and as new development causes old problems to become new again. Producers aren't going to have useful input on if the refactoring or performance suggestions are relevant - the developer poking around the existing code isn't doing what they need it to do anymore will.
gowara6521 1y ago
[dead]
jpswade 1y ago
When reviewing PRs, I would always ask about TODOs: How will this TODO get to TO DONE?
jonhohle 1y ago
// n.b.! Or // NOTE: Work for this and are just as searchable.
- s4i 1y ago
  Aren’t all code comments for noting something?
  - jonhohle 1y ago
    I typically use those when the following code does something emunexpected, relies on external state or is setting state relied on by something else. There are times where you can’t rewrite or refactor something or have Toni’s ran API with non-obvious behavior. Plus NOTE is shorter than HERE BE DRAGONS
darad 1y ago
i just add a comment saying "do xyz if you feel like it later"
toddhodes 1y ago
This is an important point, but we can do better! this is why there is a difference between TODO and XXX XXX is old-school, "popularized in early Unix-related projects like the Berkeley Software Distribution (BSD)", and acted both as TODO and warning. amazingly, now, we can simply have both! - TODO is literally "do this before merging, or, make an issue" - XXX is "gah this is a bug and i can't fix it right now. i am putting the XXX so it stands out from non-bug comments"

413 points by todsacerdoti 1y ago

Fwiw i’ve see far fewer todos lately since LLMs have gotten significantly better as of late. The todo documentation is often a perfect prompt.

newswasboring 1y ago

Off topic, but this is such a great blog format. Encourages writing small things just by how it looks. I would love to make my own blog like this, does anyone know how this was done?

CRConrad 1y ago
Presumably https://news.ycombinator.com/user?id=sophiebits https://news.ycombinator.com/user?id=sophiebits , who commented twice in this discussion, would know.

it_citizen 1y ago

Then maybe those todos are not todos but just regular comments?

happytoexplain 1y ago
Then they would be lost. Comments are for understanding how something works. TODOs are for understanding how something might not work. Edit: And if you put them in a tracker, they'd be distracting and confusing for team members less intimately familiar with the codebase, e.g. a PO. You could also choose a word other than "TODO", as long as it won't produce a ton of false positives in a search.
- dorian-graph 1y ago
  What does it mean to be lost? Why would a TODO comment not be lost, versus a comment without that prefix?
- marcosdumay 1y ago
  If you put them in a tracker, soon enough there will be somebody asking why 90% of the issues are not being worked on, will complain if they just disappear one day, and will disappear for political reasons.
- jraph 1y ago
  > Comments are for understanding how something works Even better: for understanding why some code does this surprising or seemingly complicated thing it's doing

happytoexplain 1y ago

Agreed - there needs to be a space for known issues that are not worth tracking. Issues that need to be understood as real, but perhaps may never be viable to fix. Something you can ctrl-F for when you have time and are curious if there's something you can clean up. It drives me insane that so many tools/processes treat TODOs as essentially code smells.

skydhash 1y ago
I still have to come across one of those issues. It may not be a priority, but it is a broken window (Pragmatic Programmer book). If it’s a won’t fix type of issue, just add it to the software docs.
KolibriFly 1y ago
Not every TODO is technical debt waiting to be paid off

mcntsh 1y ago

To me this brings the phrase to mind: "perfect is the enemy of the good." Ideally tech debt or code-smell encountered like this would be captured/tracked/described better but often-times this means context switching or engaging in some kind of high-friction activity (like filling out a JIRA ticket) and that just discourages tracking it at all. At least inline TODOs are captured somewhere. And they can be for doing.

sublinear 1y ago
Put it in your git commit message. Most commits people make are rather bad. Instead of taking us back to the stone age with TODOs, why not encourage better tool usage? Many don't commit often enough and instead tangle together unrelated changes. The cherry on top is when the commit message is just "updating somefile.py" or something similarly unhelpful.
- mcntsh 1y ago
  How would that be discovered? If I inline a TODO comment calling out some tech-debt that I (we, our team) had to take on, then in the future when the next person touches that logic they will see that comment and might address it. If it's in a commit message it might as well be invisible.
  - sublinear 1y ago
    Discovered by other devs? git blame. Discovered by the rest of your org? I don't see how a TODO in the code is more visible than a git commit message. In fact, at least it's possible that non-devs may still be able to see the git commit messages in a feed or have read access to repos.
    - mcntsh 1y ago
      Instead of relying on people actively checking the git-blame for all of the code they're reading, why not just put a clearly obvious comment within the code itself?

sublinear 1y ago

TODOs are a code smell. If there's a known unhandled edge case there should be conditional logic guarding against it. If the original author dislikes the idea of a refactor... well too bad it's not their decision anymore, but they should have at least been kind enough to write tests.

happytoexplain 1y ago
This is unrealistic, or possibly you just haven't used platforms/languages that benefit from a layer of record-keeping lower than is appropriate for a ticket-tracking system. Also, a TODO doesn't mean you have not guarded against an edge case. A TODO could be anything that increases the health of the codebase or application. You can guard against an edge case, and then write a TODO on that guard that mentions that you'd like to recover from the edge case, rather than simply guard it.
- zahlman 1y ago
  >This is unrealistic While I don't necessarily agree with GP, this isn't a refutation. Yes, eliminating code smells entirely is, in typical development environments for sufficiently large projects, entirely unrealistic. That doesn't make them not smells.
ebiester 1y ago
Sometimes, it's "there is something wrong here but I cannot figure out a way to make it better yet without working nights and weekends for the next three months with no benefit to myself."
blitzar 1y ago
There is always an unhandled edge case
gabrielhidasy 1y ago
TODO: Remove the 'FillInData' function call after bug/<id> is fixed.

ipince 1y ago

But the second example there shouldn't be a TODO then, but just a NOTE (or regular comment).

basfo 1y ago

The example in the article: > // TODO: If the user triple-clicks this button, the click handler errors because [xyz] looks more like a comment than a real TODO to me. I agree that comments like those are useful, but shouldn't be a TODO. A TODO implies a specific type of comment. One that implies a task, points to something that should actually be done (like TODO: This function should return another value with XYZ). And I agree that the proper place for that is a tracker, not buried in the code. In the example just documents a bug. , there is no actual action. In my experience, TODOs are often a way to get quick and dirty code approved in a PR. They usually never get done, they're just a way to push the responsibility onto some future developer who "will have more time" (which means it will likely never happen).

sophiebits 1y ago
Comments are usually for explaining why code is doing what it’s doing. If you write just // If the user triple-clicks this button, the click handler errors because [xyz] then it’s less clear at a glance that this behavior is undesirable. Is this a bug, or is it supposed to be this way? “TODO” is a quick marker that (to me) means “here’s something that is not ideal and may be worth keeping in mind if you are working on this code”. If you or your reviewers know that it’s not OK for the fix to never be implemented, then of course, track it somewhere where it will get done. My experience is that discouraging TODO comments leads to less-documented code, not better code.
- kstrauser 1y ago
  I think that's a case for "NOTE", which has the semantics of "this is something unusual and significant to pay attention to". Edit: BTW, my specific disagreement is with using "TODO" to mean different things. I'm otherwise completely on board with the kinds of comments you're asking people to write, even if I'd label them differently. When I'm trying to understand new code, much of the effort is in trying to figure out why the author chose the approach they did. Why'd they do this instead of the more usual approach? Did they understand the tradeoffs, or just find things on Stack Overflow or ChatGPT? Did they take this edge case into consideration? Seeing their thinking is vastly more useful than // Add two numbers three = one + two

TOGoS 1y ago

When I have a thought about how some piece of code could/should be improved, but it's not urgent, instead of // TODO: Refactor this by doing X, Y, Z I'll say // Hmm: This seems brittle. We might want to X, Y, Z this such that W. My IDE will list all the TODOs and I don't like to clutter that list with stuff that isn't strictly necessary, but it is nice to have some string--"Hmm:", in this case--that I can grep for or recognize as indicating that I thought about this already.

singron 1y ago

I have a similar philosophy for low priority tickets. Some people say it's not worth filing a low priority ticket since we can't even do the medium priority ones. I think it's still valuable since (1) it let's you write it down to remove it from your mind, and (2) you can track repeated instances or anything else that might cause you to increase the priority.

pisipisipisi 1y ago

I add and grep for the following: - FIXME: this is clearly broken/wrong and highest priority - XXX: this is “ugly” or assumes wrong things, probably higher than next - TODO: at some point, implement a whole different approach/category/branch - NOTE: code comment with a higher importance than just random comment NOTE: I work a lot with old/unmaintained codebases where “code is truth”, so there is no “jira ticket creation” but amending things as you read.

radlad 1y ago
This is pretty much what I do too. `XXX` is "Look here! This is important!" or "You might not expect this!" I rarely use NOTE, but I have on occasion.
- jackpirate 1y ago
  What's the origin of XXX? I've seen FIXME/NOTE/TODO all over the place, but never encountered XXX before.
  - pisipisipisi 1y ago
    Amsterdam.
  - slongfield 1y ago
    It has some ancient history as a morse code distress signal: https://regulatorylibrary.caa.co.uk/923-2012/Content/Regs/03800_1._DISTRESS_AND_URGENCY_SIGNALS.htm https://regulatorylibrary.caa.co.uk/923-2012/Content/Regs/03... And it shows up in some old BSD code: https://www.snellman.net/blog/archive/2017-04-17-xxx-fixme/ https://www.snellman.net/blog/archive/2017-04-17-xxx-fixme/ But... I think repeated letters are just easier to type than any other string, and since X looks like the classic "marks the spot" logo, it's what people jump to.
  - 1659447091 1y ago
    I always thought it was from Java, but that's probably a personal bias; I am sure it was used long before Java was a thing. I did find this though (archived from 1999): https://www.oracle.com/java/technologies/javase/codeconventions-programmingpractices.html#395 https://www.oracle.com/java/technologies/javase/codeconventi...

titzer 1y ago

I have three levels: 1. An issue tracker, even if it's just a text file for some projects. These are things that need to get done over the long term. 2. TODOs. These are actually bugs or incomplete things. The code is not actually done. Something isn't handled, something isn't right. Big or small, but usually small. 3. XXXs. These are performance enhancements or refactorings. It's XXX because it's obscene that this code looks this way, because it's either ugly, slow, or gross. But the code works and is tested.

pkilgore 1y ago

My whole thing here is that this is just as effective of a comment without the todo prefix. Lint the TODO part before merging, then TODO becomes a nice thing you can grep for on your own branch, like a note to yourself.

nevermore 1y ago

As a proponent of "TODOs should always point to a concrete issue", you have 3 ways to resolve a TODO before merging: 1. Just file the issue. If it's something you should actually do, you can take 20 seconds to write it down and track it. 2. Just do it. If it seems like too small of a thing to file an issue for, fix it before you commit it. 3. Turn it into a comment. If it's not worth fixing and not worth tracking, but you want to remember it, that's a fine thing for a regular code comment. Eat your broccoli. Track your todos.

mcntsh 1y ago
I wish tracking took 20 seconds. In my org (big tech) a JIRA ticket has 10+ required fields.
- hinkley 1y ago
  Jira is awful because it has no opinions and leaves those decisions up to people who have terrible ones.
  - indoordin0saur 1y ago
    Jira really seems to have degraded as it has become increasingly bloated. I grit my teeth every time I hear platform ops say "hey, that deployment ticket last week... we noticed you didn't fill out the x, and z fields and also didn't create a follow-up ticket for future deployment to prod with the correct link to the implementation ticket"
    - maccard 1y ago
      That’s nothing to do with jira and everything to do with your platform ops team.
      - hinkley 1y ago
        That’s only true if you think the person who made the torture device is not culpable for their customers using it as a torture device. I don’t happen to believe that is true. Pandering to customers makes you part of the problem.

baalimago 1y ago

// TODO(<issue-tracker-id>): <Short description> This format allow for quickly finding the place where the thing needs to be done, while keeping track of the issue in the issue tracker. I often write the issue tracker ID's in my code to add additional context. It works especially well for bugs which are reproducable in programatic tests. Then I name the test specification after the ticket, so that it's known that this bug doesn't resurface as regression.

allthedatas 1y ago

I also use a tiered strategy and FIXME for things that really need to be fixed or I have a solid idea what the next step would be to fixing it. TODOs are something less solid than a FIXME and are also just about getting it out of your head so you can devote more mental energy to something else or just relax. Maybe the idea is not fully formed yet, maybe you are not sure you really want to do it, maybe it is waiting on something else, but it needs to be captured or you will have to keep thinking about it lest you forget. As soon as I write down a TODO (code or other) that was only in my head, I can relax a little more, because now it's captured for future reference.

lmc 1y ago

In my code these days, I have: TODO SHOULDDO COULDDO The TODOs generally don't make it to main, the others sometimes get picked up eventually.

ivanjermakov 1y ago
I think common terminology for there are FIXME, TODO, XXX in that order, but YMMV
jffhn 1y ago
I only use "TODO" eventually followed by a sub-classification like "TODO bug": it maximizes discoverability by other devs and tools, and allows for a lot of variants (both technical and/or functional) while still permitting a complete scan with a single grep.

kstrauser 1y ago

I couldn't disagree more. TODO is basically an action list you search with grep. When I'm looking for things that could be done, the last thing I want to do is to have to mentally filter out the things that aren't actionable. That just makes the process use a lot more mental energy than necessary. It also leads to unproductive conversations like "we have 147 TODOs, but 18 of them actually need doing at some point, which is an improvement from last month's 123 TODOs with 22 real ones". No, please, do not do this. As notes, those are wonderful things to add. They're the sort of comments I want to see in the code I'm reading! Keep them! But don't label them as TODOs, for the same reasons that you wouldn't use Reminders as your combined actions and notes app. Edit: In addition to the mental energy, your brain eventually gives up and becomes blind to them. Then you tend not to see them at all, even the actionable ones, unless you step back and dedicate even more mental energy to mindfully going through them one at a time to give them a fair reassessment. This gives me more ADHD-fueled anxiety than I can describe.

muzani 1y ago
"your brain eventually gives up and becomes blind to them." This is not a bad thing if they are not for doing. They're there to mark that the code is incomplete but not broken. The actual to do is a FIXME.
- kstrauser 1y ago
  It's a bad thing if you're using the same tag for "we need to change this" and "this is something we might eventually consider". Imagine looking in your bug tracker and seeing a thousand tasks with no differentiation, no tagging, no priority marking, and trying to decide what to do next. Only things that are genuinely actionable should be marked as actions to be done. If it's just something you'd like to clean up, eventually, given infinite free time, label it as a note. Otherwise you're blowing up the amount of information you have to sift through when deciding what work to do.
  - sfink 1y ago
    I'm not sure you're disagreeing with the post you're replying to? I tend to use FIXME for things that really do need to be fixed, and will not push code containing a FIXME comment. Grepping for FIXME is useful. I tend to use TODO for things that I'm thinking may be useful, but aren't necessary (yet). Sometimes it'll be "TODO: Figure out whether..." or "TODO: Validate this by measuring the impact, to see if it'd be better to do something more complicated or simpler." I could rewrite all of these as regular comments -- the latter might be "I have not validated the assumptions here via measurements; something simpler might be good enough." But the TODO is a little more direct. Grepping my code for TODO isn't that useful. (Well, save for the comment block at the top, where I tend to leave actual todo comments, but they're still future tasks not FIXME-style "do this before landing" tasks. And I label them with [ ] checkboxes, not "TODO".) So we agree: don't use the same tag for both. It sounds like you use TODO for "we need to change this" and I use FIXME for that. I suspect we all have a broad range of labels: TODO, FIXME, NOTE, plain comments, comments linked to bugs, etc. When reviewing teammates' code, I check whether their TODO comments should have a bug link, should not say "TODO", should be removed entirely, or whatever.

ivanjermakov 1y ago

I have never seen TODOs being cleaned up in enterprise environment. Therefore our team would not approve PR with TODOs: either fix them yourself or open a separate ticket for it.

dboreham 1y ago
There's no back-link mechanism for a ticket. If there were (when viewing the code there's some visual queue that there's a todo ticket open for this line) then I'd agree. Also consider the infuriating practice where managers (often with the help of supercilious bots) close tickets "just because".
- CRConrad 1y ago
  > There's no back-link mechanism for a ticket. Of course there is: Put the ticket number (or URL) in a comment.

dkarl 1y ago

This is a great example of a practice that is pragmatic and smooths the way for future polish if the software grows in usage by 100x, without investing a bunch of effort now that won't make sense if it doesn't grow (and might stop you from doing the things that will enable it to grow.) If usage takes off by 100x, someday somebody will be tasked with clearing up errors in Sentry (or whatever) so bugs and regressions are easier to spot, and this comment will save them hours of debugging. However, I think using TODO to flag it is a poor choice. Good luck explaining to your teammates, "We use TODO to communicate that we aren't going to do something." I doubt you're going to get consistent adherence to such a counterintuitive convention. Instead, I would prefix the comment with "KNOWN ISSUE."

owlstuffing 1y ago

Replace the not-TODOs with NOTEs. For example, this TODO: //todo: factor this out in case X …is a NOTE, albeit a gratuitous one. Because if X ever happens, the note won’t matter anyway, since you will have had to grok all the related code to refactor. You will see this note while you’re refactoring the surrounding code and smirk, “yep, that’s right”, or “no, it doesn’t really fall out that way.” Either way, most TODOs/NOTEs like this just get in the way.

zahlman 1y ago
To me, "NOTE" still implies that the comment is about describing the existing state, rather than a desired future state.

kamens 1y ago

I love this TODO approach not just for what it does for future readers as Sophie notes but also for the mental release it gives me when thinking about edge cases that I don't want to commit to fixing. PS Hi Sophie!

sophiebits 1y ago
Hi!

gblargg 1y ago

They capture information you have when writing the code that communicates something useful about it.

ngruhn 1y ago

Strongly agree. I think of TODO as a task that might be interesting for the next person who stumbles over this code. "This logic is not great. If you happen to refactor this entire feature consider changing this thing as well". The TODO can even have an associated ticket but because it's right in the code it's more discoverable. Otherwise, the next person to change the code might even complete the ticket without knowing it.

paulddraper 1y ago
"Ideally, this code would X. It's acceptable that it doesn't, but if you do change it, considering doing this differently."
luckydata 1y ago
then it's not a TODO, it's just part of the comments. Promoting semantic diffusion IMHO is not a good practice in software development.
- paulddraper 1y ago
  How would you quickly identify something as "would be better if." It's a "to do" but on a long (perhaps indefinite) timeframe.
  - CRConrad 1y ago
    > How would you quickly identify something as "would be better if." [? -- my addition // CRC] How about by writing a comment containing the words "would be better if"?

tonnydourado 1y ago

Second todo isn't a todo, should be a trade-off comment. Something like "Technically, this will raise an error if the user triple clicks the button, but most people ain't that fast, so screw it"

rglover 1y ago

This is just going to lead to things not being done as nobody knows whether or not the TODO is resolved or not. Personally, I tag my comments in one of two ways: 1. // TODO: <task> (if multiple things, I do a multiline comment with Markdown-style checkboxes next to each item in the list). 2. // NOTE: <explainer> The former is what you'd expect (I routinely search for these to make sure I'm not missing minutiae) and the latter is for code that can't be refactored to make it clear and requires some explanation. Doing this consistently has really saved my bacon over the years (both in terms of keeping track of tasks and remembering why I had to use that ridiculous chunk of code to get something to work).

x______________ 1y ago

Off topic, what did the detective say to the developer? TODO, TODO, TODO TODO TODO TODO TODOOOOO ...No? Ok fine, how do you track completed TODOs? With TADAs! Ok fine, I'll show myself out. // TODO: Find better material

deadbabe 1y ago

If your TODO isn’t actionable, I’m deleting it. Too bad. Bury your skeletons elsewhere.

CivBase 1y ago

> But the `// TODO:` doesn’t need to be a plan to actually do something. Instead, it’s a note about “here’s an edge case that wasn’t handled” or a suggestion for a better structure that the author didn’t make time to implement — it captures a little slice of the author’s brain and gives a little window into the rich context they had at the time they wrote the code. Sounds to me like this should just be a regular comment. Don't add "TODO" if you're not actually going TO DO it.

malkosta 1y ago

If it's not intended to be done, then you are using the wrong name. Don't call it `TODO`.

indoordin0saur 1y ago
Sometimes "TODO" means something you would do if you had infinite time, refactor the code completely or something that will likely need to be revisited in the future but currently adds no value to implement.
- malkosta 1y ago
  TODO is a pretty clear name. If it's not to be done, then it should be just a regular comment, no need to tag as TODO.

Tokumei-no-hito 1y ago

OP, have a look at todo tree: https://github.com/Gruntfuggly/todo-tree https://github.com/Gruntfuggly/todo-tree it's a game changer while solo or on a team. and I’m sure it's reproducible outside of vscode (it's just highlighting depending on the todo token used). been using it and introducing it to teams for years. it's even more helpful now with AI.

gabrielhidasy 1y ago

What? What's 'TODO' about the second TODO in the article? >> // TODO: If the user triple-clicks this button, the click handler errors because [xyz] That could be a simple comment, but if its a TODO it should be ´TODO(bug/<id>): Fix triple-click error in this button´. If you really want to tag a normal comment, what about // NOTE?

luckydata 1y ago

I rarely find reasons to disagree so much with anything I read like I did with this blog post. Seems like the author lacks rigor and then goes looking for ways to excuse being sloppy, that's an attitude I don't think is productive or creates anything positive in the industry.

OutOfHere 1y ago

If a TODO is not for doing, it should be recorded as a NOTE, documenting the limitation instead of the task.

escobar_west 1y ago

This article should expand more on what TODOs are actually for, in that case. What's the difference between a regular comment (which is what the example in the article clearly is) vs an actual TODO comment?

pamelafox 1y ago

My personal philosophy is that TODOs should only be used while working on a branch. Once its ready for a pull request, any pending TODOs should be abandoned or logged in an issue tracker.

morsecodist 1y ago

I think this is fair. Untracked TODOs should be minimized but I think there is value in recording how some section of code could be improved even if you know you are unlikely to do it. I don't think the triple click thing is a good example because that seems like a bug to me. An example from my codebase is that I implemented a daily scheduled job that may display inconsistent results during short time per day it is running. Realistically fixing this will never be worth my time, this is a transit app and it is scheduled to do this at night when the buses aren't running and it will only be inconsistent if they change the schedule after already publishing it for a given day which happens pretty much never. It is also a personal project with no issue tracking. Eventually I will rewrite this loader logic to support multiple transit systems so it is good to have my notes of how I would do it better next time. Also, if this does result strange schedule behavior I would immediately go to this file and see my explanation of the flaws with my approach. Maybe I shouldn't call this a TODO but it seems like a good fit.

kentonv 1y ago

This is a style issue. Different people can have different definitions and cultures around TODOs. My codebases tend to use TODO exactly as described here. A TODO is really just a comment documenting the implementation -- specifically, documenting something that is missing, but could be useful. It doesn't mean it actually needs to be done. IMO it doesn't make sense to use comments in the codebase itself as an actual task list, because priorities are constantly changing. Things that seemed important when you wrote the code may turn out not to be, and things that you didn't think of when writing turn out to be needed. Are you constantly submitting PRs just to update the TODO comments to reflect current thinking? I mean, sure, I guess you could do that, but I think it makes more sense to maintain that list in a bug tracker or even just a text document that can be updated with less overhead.

metalrain 1y ago

I think TODOs are great for refactors you cannot start right now. It's very local, this code should change but it might not be possible during the timeframe I've been given. For future reader it might give hint what to change or what is wrong here.

Arainach 1y ago

Hard disagree. If you're not going to file a bug or ever do it, don't write TODO // TODO: If the user triple-clicks this button, the click handler errors because [xyz] This is documenting what currently happens. It's not TODO, and that word shouldn't be in the comment.

kaashif 1y ago
Yeah, TODOs should start with a verb which tells you to, you know, DO something.

thenoblesunfish 1y ago

It seems pointless to write "TODO" if it's not, you know, to do. Yes you should write comments describing ways the code can be inproved, but those can just be comments that don't confuse other people, not to mention trip all sorts of code highlighting and automated checks.

phtrivier 1y ago

I've certainly overdone it. When I left a job after many years, my collegues printed a listing of all my // TODO(pht) . It was big and full of things that never got "TODONE".

deleted 1y ago

[deleted]

owlbite 1y ago

My policy: If it's a real TODO, it includes the ticket number/link tracking the actual fix. Otherwise it should either be a regular comment or not exist.

fellowniusmonk 1y ago

TODO: Action item that must get done at some point. TODO? or ?TODO: Documenting funky code that the developer can't triage at the moment without losing flow state but is "off". Instead of a separate MAYBE any action should have an indicator of confidence level. We are marking the developers intuition about something they have run into, human intuition is both important and fuzzy, we should mark it as such. The more ? the fuzzier it gets. Humans have a bunch of symbols in their brains, we may disagree about the symbols usage but if a developer has a small thought about a codebase let them get it out quickly and with clarity. The real problem is that unified tooling for plaintext editing and zoomed out team project management don't have a good interface that let's people notate with the level of friction commiserate to the importance of the notation.

perfmode 1y ago

For cases like the one described in the article, I prefer NB comments. // NB: If the user triple-clicks this button, the click handler errors because [xyz]

rustyminnow 1y ago
What does NB stand for? Edit: "Nota bene" apparently: https://en.wikipedia.org/wiki/Nota_bene https://en.wikipedia.org/wiki/Nota_bene

nektro 1y ago

great post

dgunay 1y ago

I think there are lots of valid ways of using TODO comments. In my org, TODO comments trigger the linter, so they usually have to be addressed, downgraded to a regular comment, or turned into a ticket. They're a nice way for me to mark places I need to remember to come back to before I put something up for review. I sympathize heavily with the viewpoint that pushing these things into ticketing systems means they're less likely to get done. I think it's nearly impossible to lobby for TODO: comments to get done against a never ending stream of ultra important high business value work. Leaving these concerns inside of the codebase itself is one way that programmers can take back control when technical concerns and code quality are dismissed or deprioritized constantly.

0x457 1y ago

Interesting, yesterday I was looking at the source code of some library, and noticed a lot TODOs scattered all over. At first, I thought it's a red flag and I shouldn't use this library. However, once I read them all of them, were exactly this: very rare edge cases, minor optimizations, and notes about future optimizations possible optimizations. I pretty much immediately adopted this style of todos.

pkghost 1y ago

for the laconic and latin-leaning, NB (nota bene) means "note well"

indoordin0saur 1y ago

Title is a little click-baity but I fully agree with the sentiment. Just minutes ago I had this experience where a #TODO marked out some extremely rare edge case to handle but one that I have never seen actually occur in the 2 years since I put it in there. Still it will be useful to others (and future me) when I look back at the code and wonder why something wasn't handled. I also agree with users that sometimes these should just be comments. Really depends on your environment and since I work on a team of 2 who maintain my portion of the codebase I stick with using TODOs in this way (seomtimes).

MathMonkeyMan 1y ago
I was on a team that used `// TBD: [...]` for this purpose, so that the "TODO people" wouldn't notice.
- CRConrad 1y ago
  Add to that: // PBD: Possibly be done...? // NBD: Not being done! And, Idunno, perhaps some more.

almosthere 1y ago

Introducing TODO.ai where we handle all your todos for you

joaomeloplus 1y ago

I see comments as a failure of my prose capacity at coding. I try to commit code that should be able to explain itself as if it were accompanied by any comments. But if something is too confusing to be maintained by someone else (like me 6 months from now), then I use a comment. But that is a sad moment because I also know that this future person can update the code and not update the comment, then the thing becomes even more confusing. TODOs should never be in committed code; they should live in your project/issue management system.

Detrytus 1y ago

I think some of the TODOs are used to silence programmer's guilty conscience and protect their reputation in the eyes of future maintainer (which might be their colleague): "I know this code sucks, and this is how it can be made better, it's just my PM was pushing me to finish this task ASAP"

pkghost 1y ago

for the laconic and latin-familiar, NB stands for nota bene, or "note well".

bilekas 1y ago

Maybe I'm strange but I'll throw TODO In my code as I'm working through it, usually alone the lines of "double check the chain here later" When I'm then doing my final commit I'll do a search and check them off.. Theyre incredibly useful. I use pen and paper too but they go missing

FpUser 1y ago

I have 2 kinds of TODOs in my code: // TODO: optimize something, refactor, blah ... // TO_F_DO: this thing is gonna blow up, can't fix it now but do it ASAP TODO - when I have nothing to do I browse those, pick the on I like and do it. TO_F_DO - if I find more than 1 in my code I am suicidal

cadamsdotcom 1y ago

For that reason I’ll often prefer the word REVISIT instead of TODO. Kinda less obligatory.

bippihippi1 1y ago

sometimes I use todod for regex search and replace to refactor later. like to mark all the places where I want to later change the logging level, but for now I want to info log the query headers.

ShadowBanThis03 1y ago

WTF is "TODO?" Step one is: learn English.

laserbeam 1y ago

This short article is not about TODOs, it’s about good comments, in general. Any comment that gives you context about edge cases, about why some decision was made, about why other approaches went wrong is great! I would argue TODO means “intent to implement”, and they should be regularly converted into either tasks, documentation or just standard comments without a special keyword.

bambax 1y ago

> Ehh, maybe I’ll just leave it the way it was in case the original author knew something I don’t. That's probably the main point of code comments in general: to explain to the future reader or maintener (who may be your future self) why things are the way they are.

KolibriFly 1y ago

TODO's sometimes just a breadcrumb for future devs (or your future self) to understand the why behind a weird decision or an unhandled edge case

bravesoul2 1y ago

It is noise and correctness of the TODO needs to be maintained over code changes. Todos IMO should be limited to branches but not merged to trunk.

azangru 1y ago

> But the // TODO: doesn’t need to be a plan to actually do something. Instead, it’s a note about “here’s an edge case that wasn’t handled” or a suggestion for a better structure that the author didn’t make time to implement Why is it a TODO, and not a NOTE or something?

voidUpdate 1y ago

To me, TODO is something that I need to do. For example, I recently did a large refactor on a codebase, and commented out some large function blocks, just so it would compile and run properly, just with some functionality missing, but I left a TODO saying that I needed to actually implement them so I could find the blocks again. TODO is something you need to do, not just a remark about the code

ahoka 1y ago

TODOs are rain checks on technical debt. They are perfectly fine, leave them alone!

stephenhandley 1y ago

Effective TODOs capture a code-level design tradeoff and any associated debt which - won't have sufficient positive impact on the bug/feature you are working on - you don't have time to address at that point in time - are significant enough to require pay down later How to address them in terms of tooling and process is a way bigger question

alex-moon 1y ago
I think this is a really good way to think of it actually. My business partner and I often have this back and forth: "Do you want this done the right way or the fast way?" Most often we do a "happy medium" between the two and accept that there is work to be done in the future. This is not a bad way to do it, as more often than not the "right way" actually needs quite a bit more customer research first - often pushing "Todo" code to production reveals the use cases that show that the suspected "right way" was wrong, and the actual "right way" is to burn all the code and use a completely different existing module to do it instead, consolidating what were (incorrectly) understood to be different use cases. This is probably my favourite way of paying down technical debt.

damnever 1y ago

I think we should better differentiate between HACK and NOTE from TODOs.

cjfd 1y ago

Well, if TODOs are not for doing, how about just not putting 'TODO' in front of them? Maybe we could sometimes attempt to use words to stand for what they actually mean. Could that possibly be helpful for peoples understanding? Also, the first and most important place for putting TODO's is the issue tracking system so I think in most cases they do not have to be in the code. I might allow them occasionally if they refer an issue in the issue tracking system. Another use of TODO comments that is not necessarily bad is if you yourself or someone else is supposed to resolve all of them before the relevant code is merged into mainline.

MaulingMonkey 1y ago

Externally visible issue where external parties (producers, co-developers, artists, designers, ...) need communication about fixes and timelines? Put it in the issue tracker so people can subscribe, elaborate on repro steps, share links so QA can learn how to verify it's broken / fixed, etc. Something that needs to be fixed in your local changes before committing, lest something break terribly? Put it in code in such a way that your CI system will reject integration. That can be a // TODO or // DO_NOT_COMMIT comment that can be recognized and rejected by your git pre-commit hooks. Perforce lets you stage and describe changelists before committing them, and you can make hooks that will reject TODOs in those descriptions as well. In a pinch, #ifdefs to check for CI and a static_assert(false, ...); might be another option. One of my more common uses of this pattern is when extending or refactoring a platform abstraction layer - it tends to be easier to get it working on one platform first, and forgetting to test it on a second platform can be very easy. Switching contexts to an external issue tracker for things that nobody but yourself will ever read isn't adding value - keeping it in code where you can build safeguards that will literally prevent you from doing the wrong thing by accident will. Internal refactoring or performance improvement suggestions? Those often go in the non-blocking non-tracker // TODO bucket for me. They can safely rot away unnoticed for 10 years without causing problems as issue trackers come and go, then suddenly become relevant as new needs cause new development, and as new development causes old problems to become new again. Producers aren't going to have useful input on if the refactoring or performance suggestions are relevant - the developer poking around the existing code isn't doing what they need it to do anymore will.

gowara6521 1y ago

[dead]

jpswade 1y ago

When reviewing PRs, I would always ask about TODOs: How will this TODO get to TO DONE?

jonhohle 1y ago

// n.b.! Or // NOTE: Work for this and are just as searchable.

s4i 1y ago
Aren’t all code comments for noting something?
- jonhohle 1y ago
  I typically use those when the following code does something emunexpected, relies on external state or is setting state relied on by something else. There are times where you can’t rewrite or refactor something or have Toni’s ran API with non-obvious behavior. Plus NOTE is shorter than HERE BE DRAGONS

darad 1y ago

i just add a comment saying "do xyz if you feel like it later"

toddhodes 1y ago

This is an important point, but we can do better! this is why there is a difference between TODO and XXX XXX is old-school, "popularized in early Unix-related projects like the Berkeley Software Distribution (BSD)", and acted both as TODO and warning. amazingly, now, we can simply have both! - TODO is literally "do this before merging, or, make an issue" - XXX is "gah this is a bug and i can't fix it right now. i am putting the XXX so it stands out from non-bug comments"