[HN Gopher] TODOs aren't for doing
___________________________________________________________________
TODOs aren't for doing
Author : todsacerdoti
Score : 237 points
Date : 2025-07-22 13:43 UTC (9 hours ago)
(HTM) web link (sophiebits.com)
(TXT) w3m dump (sophiebits.com)
| it_citizen wrote:
| Then maybe those todos are not todos but just regular comments?
| happytoexplain wrote:
| 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 wrote:
| What does it mean to be lost? Why would a TODO comment not be
| lost, versus a comment without that prefix?
| marcosdumay wrote:
| 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.
| happytoexplain wrote:
| 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 wrote:
| 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.
| mcntsh wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| I'm actually saying people can do both.
|
| What I take issue with is low quality writing. TODOs are
| a low quality comment. Commit messages that only tell
| "what" and not "why" are also low quality. Generally just
| not having a clean history to look at is bad project
| management.
| darkwater wrote:
| `git blame` is to answer the question "who did this, when
| and why?", where the who and when are automatic and the
| "why" is a responsibility of the committer (and
| reviewers).
|
| A TODO is about something that is not there yet.
| bcrosby95 wrote:
| Most commit messages are bad, but commit messages are a
| terrible TODO list.
| sublinear wrote:
| You're right they are a terrible TODO list, but old
| comments in the code are worse because you don't have as
| much context to work with.
| dietr1ch wrote:
| I'd rather see a TODO in the source file than in the commit
| message because of discoverability issues with commit
| messages.
|
| Maybe that can be fixed? If I need to git blame the right
| line, and while ignoring miscellaneous commits like
| formatting changes, renames, and additional comment
| additions, then I'm probably not going to find the commit
| message. Also, if you do all of that just to find a vague
| commit message, then why bother digging next time?
|
| Best tech-debt tracking I've seen is in the form of TODOs
| with mandatory links to the issue tracker (thanks to a silly
| regex pre-commit/pre-submit check) coupled with a team
| culture of adding such TODOs, as just adding the regex check
| will just cause lazy and sloppy engineers to not add a TODO
| at all, especially when facing pressure from other teams.
| sublinear wrote:
| Maybe this is what you're thinking of?
|
| git log -pM --follow --stat -- path/to/your/file
|
| This will get you all the changes a file has gone through.
| You can also add --ignore-all-space if that's a problem.
| inetknght wrote:
| > _Put it in your git commit message._
|
| Yes, that's fine. Developers can _also_ put TODOs in their
| 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?_
|
| I have a tool which fails if it finds a TODO in a comment
| without a Jira link on the same line. Since it fails if it
| finds such things, it's great for CI/CD piplines to block PRs
| until all of the oddball ends have been tied up and made
| visible to the product team.
|
| Alas, if we could get the product team to prioritize those
| TODOs then they can start to be removed from the codebase...
| iotku wrote:
| I'm sure in larger codebases it can get unwieldy with tons of
| TODOs from a lot of different people, but for personal projects
| I've always found them a good compromise.
|
| For me it's saying "yeah I know it could be better but I'm not
| going to break my train of thought over this and context
| switch. It's not so critical as to break functionality, this
| would just be nicer."
|
| I really do appreciate TODO hilighting in editors for the odd
| occasion where I get back to something on a whim and feel like
| doing a quick fix then. (It's probably not realistically that
| common though and most will sit there indefinitely)
| dijit wrote:
| I really appreciate the feature of Jetbrains IDEs whereby the
| codebase is indexed for TODO comments.
|
| I often find myself with some time on a plane and cracking
| open my laptop to dig through to the TODOs that are shown is
| really cathartic.
| bitwize wrote:
| There are readily available MCP servers for JIRA that let the
| AI fill out the tickets for you, right from inside Cursor.
| nonethewiser wrote:
| I think the main thing is sometimes you want the signal that
| there is work to be done in the code. In that case even if you
| track it on JIRA, GH issues etc. you'd still want to link it.
| And a reference is a bet on continuity so without a description
| in the comment as well you might lose the meaning someday.
| sublinear wrote:
| 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 wrote:
| 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 wrote:
| >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 wrote:
| 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 wrote:
| There is always an unhandled edge case
| gabrielhidasy wrote:
| TODO: Remove the 'FillInData' function call after bug/<id> is
| fixed.
| ipince wrote:
| But the second example there shouldn't be a TODO then, but just a
| NOTE (or regular comment).
| basfo wrote:
| 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 wrote:
| 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 wrote:
| 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
| muzani wrote:
| It's a skip. Most are fine even if they never get done. What's
| not fine is when code is not fully functioning and we assume it
| is.
|
| My favorite TODO was something like class
| EncryptedSharedPreferences with a "TODO: encrypt this". It was
| written by someone who left before I joined (I never would have
| approved it lol). But it made it clear that this code was
| indeed, unencrypted, instead of having to figure out whether it
| was encrypted by some other module or worrying that we'd
| encrypt it twice.
| zahlman wrote:
| Surely it's the _data_ that needed to be encrypted?
| GLdRH wrote:
| No, the comment.
| SoftTalker wrote:
| I dislike that as an example of a "good" TODO comment because
| for the same effort as writing that comment you could just fix
| the issue, or at least make it do something that isn't an error
| (and then maybe leave a comment such as "triple-clicks ignored
| because [xyz]).
|
| You've already gone to the effort of determining the trigger
| and the reasons for the error, so you're probably 80% there.
| WatchDog wrote:
| The example seems like more of a FIXME than a TODO.
|
| It's a clear error, but likely unimportant enough to bother
| addressing.
| TOGoS wrote:
| 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.
| AnotherGoodName wrote:
| 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.
| singron wrote:
| 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 wrote:
| 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.
| johnmaguire wrote:
| 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 wrote:
| What's the origin of XXX? I've seen FIXME/NOTE/TODO all over
| the place, but never encountered XXX before.
| pisipisipisi wrote:
| Amsterdam.
| slongfield wrote:
| It has some ancient history as a morse code distress
| signal: https://regulatorylibrary.caa.co.uk/923-2012/Conten
| t/Regs/03...
|
| And it shows up in some old BSD code:
| 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 wrote:
| 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/codeconvent
| i...
| zahlman wrote:
| Unclear, but we do have
| https://www.catb.org/jargon/html/X/XXX.html
|
| > Some hackers liken 'XXX' to the notional heavy-porn movie
| rating.
|
| This seems plausible given the older culture ("this is
| metaphorically dirty, and therefore like porn", insert
| puerile snickering) and I can recall old jokes about
| "searching for" these markings. But I think it's also just
| about it visually standing out - the X character filling
| the terminal display cell with sharp lines.
| nonethewiser wrote:
| Great in theory but these conventions are meaningless without
| tooling IMO. Assuming you are working in a team. Which is not
| to say they are meaningless - maybe there is or should be
| tooling for this.
| ericbarrett wrote:
| For me, XXX is a mental note to "fix this before your next pull
| request." If I'm being serious I'll set up CI to reject any
| code with a comment containing this string. So in that sense it
| would be the highest priority.
| p0nce wrote:
| I'm using:
|
| - TODO: will be needed before release, mandatory or else turn
| into another category. Blocks release.
|
| - FUTURE: will be turned in to a TODO eventually, optional,
| often architectural
|
| - MAYDO: nice to have, very optional
|
| - PERF: do this if more performance is needed
|
| +
|
| some semantic tags related to domain
|
| Opinion: TODOs are NOT code smells, they accrue around the most
| valuable parts of the codebase.
| zahlman wrote:
| I like these, although I wonder about the value of
| speculating about a performance optimization while neither
| just doing it nor profiling.
| sfink wrote:
| It's just saving the next person the trouble of thinking up
| and documenting the same approach you thought of while
| writing the code in the first place. As in, you know it
| doesn't matter now because the overall thing is plenty fast
| enough, but you can imagine a future where performance
| starts showing up as an issue and you wnat to leave a
| breadcrumb saying "this fruit here, it's a-hangin'".
| Nadya wrote:
| Very useful for flagging any O(n^2) that make assumptions
| about the size of N because N is not expected to exceed a
| certain size. Especially for when N inevitably exceeds that
| size.
|
| Documenting it saves the poor dev doing profiling in the
| future a bit of effort so they can come up with the better
| solution that you failed to come up with when writing the
| code.
|
| Often times code has to be written and committed and I
| don't have the time nor the brains to come up with a novel
| solution that solves a future performance issue that is not
| yet and is not expected to ever become a performance issue.
| achenet wrote:
| Personally I use
|
| FIXME: something broken that needs fixing
|
| TODO: potential features/improvements
|
| WARN: noting complex edge cases/weird behaviors
| GLdRH wrote:
| I find it weird to use TODO for something you don't
| actually have to do. But you're apparently not the only one
| to do this, and as long as everyone who's working on the
| same code is on the same page it's fine I suppose.
| Lammy wrote:
| I think in these same three categories but label them TODO,
| T0DO, and TOD0, respectively. I like that they look roughly
| the same when visually scanning through a file but are easy
| to grep for separately.
| cjbgkagh wrote:
| I do something similar, I place an assertion instead of FIXME
| for code paths that are not yet finished and can be avoided. My
| TODOs are associated with possible tasks including a refactor
| for performance or clarity. My NOTEs are for tracking
| historical information and to capture thinking at the time that
| would not be immediately obvious from looking at the code.
| jansan wrote:
| I have often thought about doing exactly this, but one thing
| that always made me hesitate was the fact that nobody else
| seems to be doing it. Now that I finally see that others are
| actually using other labels than TODO I may actually start
| doing this, too.
| marksomnian wrote:
| I like this style. In a project I worked on we had CI reject
| any FIXMEs outright and any TODOs that weren't accompanied by
| an issue ticket[^1], so the hierarchy would be
|
| FIXME: I am leaving a note to myself to not get distracted, but
| this code is not considered finished/mergeable until it's
| resolved
|
| XXX: this needs fixing soon, but the code will still be
| functional without it
|
| TODO: this needs revisiting but the code is perfectly useable
| without it - a lower priority XXX
|
| NOTE: this does something unusual and you need to bear in mind
| while working on this code
|
| [^1]: the value of doing (or not doing) this is a subject that
| has already been extensively rehashed in sibling comments
| titzer wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| I wish tracking took 20 seconds. In my org (big tech) a JIRA
| ticket has 10+ required fields.
| hinkley wrote:
| Jira is awful because it has no opinions and leaves those
| decisions up to people who have terrible ones.
| indoordin0saur wrote:
| 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 wrote:
| That's nothing to do with jira and everything to do with
| your platform ops team.
| zargon wrote:
| It feels like it takes 20 seconds just for the Jira page to
| load.
| wackycat wrote:
| // TODO refactor to make page load faster
| scosman wrote:
| Yes! I often add a CI check that TODOs are removed before
| merging a PR. Have them all you want in your branch, but do one
| of the above 3 things before merging (sometimes any `TODO`,
| sometimes `TODO_P0`).
|
| I find CI integration also makes TODOs more helpful. You can
| use them to track a genuine TODO in a working branch, but CI
| will make sure you don't miss them.
| happytoexplain wrote:
| >take 20 seconds to write it down and track it
|
| You've described a TODO.
|
| If I were to elevate it into a ticket system, besides obviously
| taking longer than 20 seconds, it would be a distraction, not a
| help.
| AnotherGoodName wrote:
| I personally have no problem with the forcing function of a
| policy that makes you add a todo to a ticketing system.
|
| It sets a bar for the todo to be at least more complex than
| creating a ticket. Any less and you can just do what the todo
| says to do.
| cjbgkagh wrote:
| Make the bar high enough and people won't bother to do
| either and instead just hope for the best or keep their own
| list of TODOs elsewhere.
|
| The point of a cheap informal method is to as low of a bar
| as possible so that more information is collected. As for
| always immediately fixing that's the same as making
| everything the top priority, the true priority is lost.
|
| Too many TODO comments and not enough tracked issues,
| that's a sign that issue tracking has too much ceremony.
| Ban the use of TODOs and you lose even that information.
|
| Perhaps a codebase could be watched such that new tracking
| issues are added and tracked implicitly when checked in by
| searching for new TODOs in the code. Similarly the tracking
| issue could be closed when the corresponding TODO is
| deleted from the code.
| hinkley wrote:
| I was just having this conversation with myself for another
| reason this morning (trying to define why automating
| processes is a force multiplier and mistake reducer). Because
| there's little to no IDE integration for ticket tracking,
| swapping to the ticket system is a context switch. And the
| ticket system has ways of demanding your attention once
| you're in there. If it succeeds now you're pre-empted.
|
| The thing about concurrency is that as long as you don't know
| about a priority message you can continue to make progress on
| the task at hand. The moment you are aware of it you have to
| deal with it or have to explain yourself later. "I didn't see
| it" goes a lot farther than, "I did but I was busy."
|
| My ex would try to check her work email on a Friday evening
| as we were on our way out the door for a trip out of town. A
| trip her boss likely knew about. That's not why she's my ex
| but it certainly didn't help. That email arrived after you
| already left, lady. That's your story and we are sticking to
| it. Don't go looking for conflict, particularly when doing so
| affects people other than yourself.
| nonethewiser wrote:
| I think the author is basically arguing for #3 but not
| addressing the difference between a `TODO` comment vs. a
| non-`TODO` comment.
|
| I guess the `TODO` terms has a certain visual flair that makes
| us immediately understand the class of comment. I guess that
| would be my best argument for keeping it a `TODO` comment
| instead of a regular one. But when you see the author arguing
| that `TODO` comments dont mean you need TO DO anything, it's
| kind of a smell, isn't it?
|
| I find myself generally agreeing with the article's sentinment
| but think your option #3 of just making it a non-TODO comment
| an improvement.
| hinkley wrote:
| Am I hallucinating or did IntelliJ have a TODO tracker?
| Webstorm doesn't bug me about todos, but something I used to
| use did.
| skydhash wrote:
| It still does. But it's a user option to run the scan when
| commiting (or pushing). So it may be disabled in your
| config.
| nilamo wrote:
| Rider definitely has a popup with a list of TODOs before
| you push to the remote. I assumed that originally existed
| in intellij... but never verified that.
| 0x457 wrote:
| Yes, it's in base IntelliJ. TODO and FIX tracking, IIRC.
| 1980phipsi wrote:
| I think the key point is that if you put a TODO comment in the
| code, it should be resolved before merging. If it's important
| enough to leave in there, it should be an issue. I only use
| them as something to grep for and so that I don't lose my train
| of that as in "oh I need to fix that but I'm working on
| something else at the moment, write the TODO, finish what I'm
| working on, then go back to the TODO".
| hinkley wrote:
| If the todo is code you're working on, yes.
|
| If it's a WTF about code that is next to the code you worked
| on, no. Boost the WTF ratio of code that deserves it.
| pornel wrote:
| Tracking in external system adds overhead not only for filing
| the issue, but also for triaging it, backlog management, re-
| triaging to see if it's still a problem, and then closing it
| when it's finished. Issues in an external systems may also be
| overlooked by developers working on this particular code.
|
| There are plenty of small things that are worth fixing, but not
| worth as much as the overhead of tracking them.
|
| TODO in code is easy to spot when someone is working on this
| code, and easy to delete when the code is refactored.
| OrderlyTiamat wrote:
| You can leave the TODO in the comments- e.g. ruff the linter
| has an optional rule to disallow TODO comments unless it's
| followed by an issue url.
|
| If you put that in the CI, then you can use TODOs either as
| blockers you wish to fix before merging, or as long term
| comments to be fixed in a future ticket.
| pc86 wrote:
| > Tracking in external system adds overhead not only for
| filing the issue, but also for triaging it, backlog
| management, re-triaging to see if it's still a problem, and
| then closing it when it's finished.
|
| Which is already what you're doing in that system, and what
| the system is designed for.
|
| Source code is not designed to track and management issues
| and make sure they get prioritized, so you shouldn't be using
| your source code to do this.
|
| We add TODOs during development, and then during review we
| either add a ticket and remove the TODO, or fix the issue as
| part of the PR and remove the TODO.
| LeifCarrotson wrote:
| I think the key distinction is that tracking in an external
| system exposes the task for triage/management/prioritization
| to people who aren't reading the code, while a TODO comment
| often leaves the message in exactly the spot where a
| programmer would read it if the possibility of a problem
| became an actual problem that they had to debug.
|
| In my experience, these can often be replaced with
| logger.Error("the todo") or throw new Exception("the todo"),
| which read about as well as //TODO: the todo, but also can
| bubble up to people not actually reading the code. Sometimes,
| though, there's no simple test to trigger that line of code,
| and it just needs to be a comment.
| baalimago wrote:
| // 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 wrote:
| 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 wrote:
| 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 wrote:
| I think common terminology for there are FIXME, TODO, XXX in
| that order, but YMMV
| jffhn wrote:
| 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 wrote:
| 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 wrote:
| "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 wrote:
| 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 wrote:
| 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.
| kstrauser wrote:
| I don't disagree with any of that. But we're talking in
| the context of this article, which includes 2 example
| comments: // TODO: Write the second half
| of this file so next week's launch won't explode
| then sure, you should probably track that somewhere.
|
| and // TODO: If the user triple-clicks
| this button, the click handler errors because [xyz]
|
| So my comment is also in that context of using the same
| tag for things of wildly different importance and
| urgency. And that would drive me to drink.
|
| Definitely come up with a local convention for which tags
| mean what, and pick whatever resonates with your team.
| TODO in your org can mean something different from mine,
| and that's perfectly fine. Just please, _please_ use
| different tags for different things, as you 're
| recommending.
| sfink wrote:
| > So my comment is also in that context of using the same
| tag for things of wildly different importance and
| urgency.
|
| Ah, ok. That's fair. I agree that the example comments
| ought to be considered different categories. That first
| one is a TODO that is for doing.
|
| > And that would drive me to drink.
|
| Is that a bad thing? It depends on what you're drinking.
| kstrauser wrote:
| I was just given a bottle of Booker's Bourbon, batch
| 2023-01 (https://www.bookersbourbon.com/bourbons/2023-01-
| charlies-bat...), but I haven't gotten the nerve to break
| the seal yet. Or since receiving it, had a day wonderful
| enough to justify celebrating with it, for that matter.
|
| Soon, though.
| zahlman wrote:
| I tend to put my _real_ action list in a separate document,
| not in version control....
| kstrauser wrote:
| But then why label things with TODO in the code, if they're
| not really things you intend to do?
| hadlock wrote:
| It's similar to logging INFO vs WARN.
|
| //this is an info level comment
|
| //TODO: change the downstream code so it's less brittle
| after we get to prod(WARN)
|
| //TODO: don't hard code this variable, had to get prod up
| and running due to leap year
|
| In my experience TODO are most commonly placed by either
| the guy doing a greenfield project, the code maintainer,
| or the guy getting production out of the ditch at 2am on
| a Saturday. I don't think I've ever seen a junior dev
| write one. My code has a few TODO sprinkled in but
| they're fairly rare, and call out where I had to make a
| decision due to constraints, and inform which direction I
| intended to take.
| zahlman wrote:
| Personally, I normally don't. But every now and then it
| just intuitively seems like the right way to phrase the
| comment. Afraid I can't really explain any better than
| that.
| eddd-ddde wrote:
| It's useful when an unrelated change unintentionally gets
| rid of a TODO and you can cross-reference it with the
| tracker item to see more context and maybe close it too.
| muzani wrote:
| They're placeholders for me. Not for everyone else. I
| can't write perfect code the first time. I may use
| hardcoded strings (instead of spending 20 mins uploading
| the string to localization). I may make a O(n^2) loop
| because I'm fixing another problem. If you find these
| TODO in a PR, you should call them out. Or I might be on
| a long vacation next week but I don't want to leave the
| branch out of sync for a long time and it works but is a
| little dirty.
|
| In some other cases, they don't have to be done now.
| They're bottom priority. A hardcoded color that won't
| work with dark mode, but we have no plans to use dark
| mode, etc.
| qwery wrote:
| Later: FIXMEs aren't for doing. FIXMEs are comments
| describing how a piece of code is less than ideal. The code
| works, of course, because we never commit non-working code --
| it could be improved, but it's not broken. The actual fix me
| is a compiler error.
| johnnyanmac wrote:
| Later: some compiler errors are just warnings. If you
| really know what you're doing, you can suppress them and go
| about your merry day. You're not paid to make correct code;
| just "shippable" code.
|
| Anyways, I'd be happy with a structure like
|
| - "NIT" that acts more like notes for correct
| implementations used for highlighting potentially better
| structures or optimization to consider farther down the
| line
|
| - TODO for issues that can or will become issues later on,
| but are otherwise functional for prototyping purposes. I
| don't think every TODO needs to be corrected, but you
| should have a refactoring day every period where you
| address most of these TODOS.
|
| - FIXME for critical or showstopper level issues, but you
| need to clock out for the day. There shouldn't be any FIXME
| in a stable branch of code. Arguably a FIXME shouldn't
| persist for more than a few commits.
| alanbernstein wrote:
| Whatever theme/packages I use in Emacs have been
| highlighting NOTE, TODO, FIXME in comments for at least
| the last 10 years, so that's what I use.
| sslayer wrote:
| My code contains no NOTEs,TODOs,FIXMEs or Comments, for
| as Programmer, I have transcended space and time to the
| final abstraction, and no longer write any code, only
| long complicated manual procedures, which I then
| outsource to third parties, who in true programming
| fashion use AI.
| ozim wrote:
| That example from article should be regular comment not a TODO
| comment.
| hinkley wrote:
| Code coverage is another, but some numpty always gets it in
| their head to go for quantity over quality and they introduce
| coverage that doesn't test shit. I will spare you my rant about
| how 85% is the optimal code coverage.
| cerved wrote:
| That's what FIXME is for
| maxbond wrote:
| Agreed, though by the same token, unactionable `TODO`s should
| probably be `HACK`s or `NB`s.
| giancarlostoro wrote:
| But also...
|
| > Most users won't end up triple-clicking that button.
|
| Absolutely they will. If they're on slow enough network speeds,
| they might get frustrated and start tapping / clicking away. I
| grew up on Dialup internet, I remember the struggle.
| windows2020 wrote:
| The most frustrating thing to find is a TODO for a half baked
| thought about some inconsequential logic. Delete!
| exiguus wrote:
| I like the idea presented by the author. This is because, in my
| opinion, classic TODOs have no place in the main branch. You
| can do whatever you want in your feature branch or on your
| local machine, but not in the shared codebase. If something is
| not ready, you are not done, and you should not commit or merge
| it.
|
| In my opinion, the author describes more of a NOTE, such as,
| "Currently, we support X because of the requirements in
| TICKET-X. If you want to support X and Y..." or "This was done
| like this because of X. The better solution is Y and it make
| sense to do the better solution when ...". I like the idea of
| helping my future self quickly understand why something was
| done in a specific way and how I can refactor it now. Also this
| indicates that how ever added the NOTE, is a good software
| engineer, that does not implement features or functionality
| that is not needed yet.
| ivanjermakov wrote:
| 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 wrote:
| 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".
| dkarl wrote:
| 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."
| kamens wrote:
| 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!
| owlstuffing wrote:
| 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 wrote:
| To me, "NOTE" still implies that the comment is about
| describing the existing state, rather than a desired future
| state.
| gblargg wrote:
| They capture information you have when writing the code that
| communicates something useful about it.
| ngruhn wrote:
| 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 wrote:
| "Ideally, this code would X. It's acceptable that it doesn't,
| but if you do change it, considering doing this differently."
| luckydata wrote:
| 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 wrote:
| How would you quickly identify something as "would be better
| if."
|
| It's a "to do" but on a long (perhaps indefinite) timeframe.
| tonnydourado wrote:
| 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 wrote:
| 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______________ wrote:
| 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 wrote:
| If your TODO isn't actionable, I'm deleting it. Too bad. Bury
| your skeletons elsewhere.
| CivBase wrote:
| > 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 wrote:
| If it's not intended to be done, then you are using the wrong
| name. Don't call it `TODO`.
| indoordin0saur wrote:
| 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.
| Tokumei-no-hito wrote:
| OP, have a look at 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 wrote:
| 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 wrote:
| 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 wrote:
| If a TODO is not for doing, it should be recorded as a NOTE,
| documenting the limitation instead of the task.
| escobar_west wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| thenoblesunfish wrote:
| 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 wrote:
| 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".
| owlbite wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| What does NB stand for?
|
| Edit: "Nota bene" apparently:
| https://en.wikipedia.org/wiki/Nota_bene
| nektro wrote:
| great post
| dgunay wrote:
| 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 wrote:
| 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.
| indoordin0saur wrote:
| 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 wrote:
| I was on a team that used `// TBD: [...]` for this purpose, so
| that the "TODO people" wouldn't notice.
| almosthere wrote:
| Introducing TODO.ai where we handle all your todos for you
| joaomeloplus wrote:
| 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 wrote:
| 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"
___________________________________________________________________
(page generated 2025-07-22 23:00 UTC)