15 ms·

Using TODO For Everything

235 points by GoldinGuy 4y ago

dfee 4y ago
I have put in many that look like `TODO: can’t foo because bar. workaround with buzz. tracking: github.com/issue/1234` or whatever. Every once in a while I go back through and clean up what I can. I think this is good.
jbverschoor 4y ago
Visual C++ in the '90s already supported all of those..
tonnydourado 4y ago
Ok, but hear me out: what if I don't use any of these, just put ToDo everywhere, and don't waste time thinking in what category the current todo should fall on? Then I book 15 minutes at the end of each day or even week to categorize everything and put into a backlog.
DrBoring 4y ago
I like to use DEBT for times when I'm writing code that I know are poor practices, and will need to be refactored, but I'm in a mood where I just want to get something built that I can see and UI test.
vodou 4y ago
For unimplemented stuff / placeholders I highly recommend exceptions instead of TODOs in any form (if suitable and your language of choice supports that). E.g. in Python: def my_fancy_function(): raise NotImplementedError
- TheRealPomax 4y ago
  But why only one or the other? The TODO is for your IDE to tap into so you can quickly and easily find outstanding work before the code is ready to be submitted as MR/PR (most IDE and even many simpler code editors have TODO/FIXME listing built in). The exception is for runtime behaviour until the TODO is resolved: it's something you do mostly for yourself, not others. By the time others see your code, your TODOs have either been addressed, or they're acceptance criteria for follow-up work in your project tracker. And that brings us to the third part that we _also_ need: the issue that the work the TODO talks about is for. Either as a checkbox task in a larger piece of work, or if it's big enough, taking up the entire issue. (because good project management means knowing what tasks are required/which work is outstanding, without opening a single file)
yosito 4y ago
I pretty strongly disagree with this. The advantage of using TODO for everything, is that it's easily searchable, and you don't have to try to guess/remember, which labels are used for your comments. If your task is more nuanced than a simple TODO, you can explain in the description after the keyword. The purpose of the keyword is to make it easy to find and take action on in the future, and moving away from using a single keyword makes it easier to miss a comment and harder to take action.
- beepbeepnewnew 4y ago
  Full agree. They also write > the value of using a broader selection of terms is that you (and therefore all the other programmers you’re collaborating with), are able to be more descriptive about what it is precisely that you need “to do.” But that's what the space after `TODO:` is for. To say what it is you need to do later. The less complexity you add, the less you have to maintain. This mainly applies to things of a certain smaller scale, but I find I encounter `TODO` in my code when I am in a certain scope or just have some free time to refactor, fix things, etc., neither of which require anything beyond a searchable string, as you mentioned. This reminds me of any note taking app that uses #tags. You start in earnest and tag things; you end up with twelve different tags for #cooking, #baking, #food, #recipes, etc. because you forgot which one was which when organizing; it falls into disarray; you are left with unusable cruft, so you end up just searching for "bread" in the search bar, anyway.
  - GoldinGuy 4y ago
    That's a totally fair assessment - I can certainly relate with tags in note-taking apps
  - shakezula 4y ago
    That exact problem you mention about tag saturation is why I switched entirely to a zettel method where notes are only organized by what they link to or from. Tag structures also just aren’t that great for later recall.
    - 4y ago
OnionBlender 4y ago
I wonder if these types of articles would get a lot less attention if the title was something less assertive like "Consider replacing TODO with something more specific".
- GoldinGuy 4y ago
  Oh for sure. I've posted on HN plenty of times and never gotten any comments - I post something short and "hot take" and suddenly get top 10 lol
HNHatesUsers 4y ago
inferense 4y ago
would it be valuable for anyone to have an inline TODO / categorised TODO automatically link to an issue tracking tool? I'm building one, and this kind of feedback would be very helpful.
brunoqc 4y ago
There was a tool a while ago that let you track bugs and implementations with comment tag inside your code. I think it sounded like "artifact", but I can't find it. I think it was abandoned, but are there other tools like that?
ThePhysicist 4y ago
Why was the title edited to say the exact opposite of what the article says? This practice seems to get a bit out of hand recently.
- GoldinGuy 4y ago
  I'm not sure - I didn't edit it and I don't know how to fix it
  - mtVessel 4y ago
    HN has some rules for automatically fixing up headlines. Usually it edits out small words like "the" and "a" at the beginning of a title. I have no idea what the rationale for this is, especially considering the potential for corrupting the emphasis of the original headline, like in this case.
- maicro 4y ago
  I noticed this as well; at first I thought this was a tongue-in-cheek response to the "Stop..." version.
- gitgud 4y ago
  According to the "HN guidelines" [1] > Otherwise please use the original title, unless it is misleading or linkbait; don't editorialize. So, "Stop using" could be considered "linkbait", which could be why it was changed to just "Using". It's ironic that this has the effect of misleading the author's intent... [1] https://news.ycombinator.com/newsguidelines.html https://news.ycombinator.com/newsguidelines.html
toss1 4y ago
Great idea overall. Rather than entirely replace "TODO" (which would then require multiple searches when a single one now finds all instances), consider augmenting it instead. E.g., TODO-FIX, TODO-DOCUMENT, TODO-ADDFEATURE... (or, if you prefer, abbreviated versions of such tags)
Joeri 4y ago
I don’t think it matters that much how they’re labeled as long as they are easy to get rid of. Before I ship something to production I try to get rid of all TODOs. Sometimes this means rewriting it as documentation of weird behavior, often it means moving it an external backlog, once in a while it is actually doing the TODO. Once a TODO ships, it is effectively a WONTDO because nobody is going to want to touch that hairy code and if it works it works.
Waterluvian 4y ago
To each their own. Mine is: TODO is a linting error and should not exist when it’s final PR time. We use them for our own feature branch dev work. Any item that’s a “do later” needs a URL for a ticket/issue in the comment. These are very rare and discouraged as usually the issue alone is enough. Don’t need to mention it in the code because even the location of the mention can basically be an opinion on how to solve the problem.
MetaWhirledPeas 4y ago
If you have to subcategorize your TODOs you probably have too many TODOs.
bachmeier 4y ago
FYI, the title of the post is "Stop Using TODO For Everything" which is very different from "Using TODO For Everything".
evanmoran 4y ago
If it helps I think of todos as thoughts for future programmers so I try to give more context including category and priority: TODO(security, p1, blocking): login must be authenticated TODO(perf, p3): update can improve to O(n) if needed TODO(data, p1, blocking): this db insert should be retried on failure
oedo 4y ago
HN in 2023: "Conventional Codetags: a specification for structured TODO comments"
j-rom 4y ago
I believe that categorizing comments will save some time down the road if you're specifically looking for something like "BUG". However, searching and aggregating all comments becomes more difficult, which is, in my opinion, one of the main benefits of using "TODO".
foxlisk 4y ago
Why is this link different in a misleading way from the actual title of the blog post? Doesn't HN usually avoid that?
shireboy 4y ago
On productivity hack: I routinely put “//TODO: you are here. (Description)” in the code before I close it for lunch or the day. This way I can pick back up right where I left off. Saves a few mental threads context switching.
Centigonal 4y ago
This is silly to me - not because using multiple tags is better or worse, but because # TODO is something I see as primarily personal shorthand, and I think it's counterproductive to prescribe tags for people to organize their own code with. If my brain likes "TODO: fix edge case" and your brain likes "FIXME: edge case," that's okay. I guess this is relevant if you're using TODOs in the main branch, but I see that as rare. There are very few times I've had someone else pick up a TODO I've written, or vice versa. In my current team, if we're passing a To-Do/bugfix/enhancement to someone, that becomes a ticket and/or a Slack conversation.
soheil 4y ago
Please don't. If you're reading a sentence in a TODO you can decide what it wants you to do, it's bizarre to claim the reader will be less confused if the sentence was merely labeled differently. This reminds of using emojis in Github issues instead of using a universal up/down vote to count the usefulness of an answer like Stackoverflow. Please don't ruin programming further.
xyzzy_plugh 4y ago
Just going to pick a single nit. > you don’t want your project to end up like the Linux codebase with 3000+ TODOs dating back over a decade. Why don't I? TODOs capture a lot of context that would otherwise be inappropriate or unseen in a comment. They're in all caps and they stand out and draw the reader's eye. They can be completely out of context, whereas comments are typically extremely contextual. They often help explain cases not covered, paths not supported, missing functionality or notes for future contributors. Splitting them into even more comments just makes them harder to find and reason about. When you're writing a TODO, you don't want to stop to smell the roses, thinking about what the future may hold, you just want to blot down the thought in your head and finish the task at hand. Not to mention that in reality it's quite reasonable: https://livegrep.com/search/linux?q=TODO&fold_case=false&regex=false&context=true https://livegrep.com/search/linux?q=TODO&fold_case=false&reg... You be the judge.
chapliboy 4y ago
Right now, I just use TODO along with a description. But the thing that has helped me and my teams most is adding a date and a name to each todo. For example, // TODO (03 May 2022 chap): This can be optimised. The date really helps because many times the TODO was written for an earlier design, and the todos haven't been updated. Many times a lot of time has been saved when trying to figure out the context of a todo. Same for author. Helps to know who made the note, in case any additional context is needed. Though often it is you who made the comment and you've obviously forgotten...
- NateEag 4y ago
  If you're using a decent version control system, the name and date can be skipped in favor of a quick blame when you actually need to know.
  - chapliboy 4y ago
    I guess that's another way to go about it. I don't know how git deals with reindenting, refactoring etc, and you might lose context, but you could probably find it again. It's kinda nice having it right there in the code though.
    - NateEag 4y ago
      I use an iterative blame tool (magit-blame in Emacs) and it generally does pretty well for me. I prefer having the author out of the way and looking it up when I'm curious. I can see how others might prefer the opposite.
Xen0byte 4y ago
I would strongly argue against this. Not only TODO is easily searchable as others have also pointed out, but also in some IDEs you can open a TODOs window which will aggregate all of these so that you can easily keep track of them (e.g. Visual Studio).
dobrinov 4y ago
I would say “Don’t use TODOs (in your code) at all”. They are just “broken windows” in your code. If something is a bug and you think that it is important to be fixed - just do it. If you think that something has to be done but it is out of the scope of your current task, note it down somewhere and take ownership of making it happen one way or another. Leaving a comment in your code just puts this responsibility away from you. In my experience this does not work and those type of tasks just pile up.
spacemanmatt 4y ago
Ok but my tooling defaults recognize TODO and I have many pending deaths on other hills of higher precedence.
- ezekiel68 4y ago
  Yeah? Well, this is why Jedis do not get their light sabers from Acme Megacorp.
- philote 4y ago
  Exactly. Plus if I want to find things to fix in my code, searching for TODO is much easier than searching for each of a dozen or so other strings.
  - PrimeDirective 4y ago
    And I can add additional information next to the todo: // todo: todo
    - bee_rider 4y ago
      As long as the second todo is also standardized (TODO: FIXME), so it will play nicely with grep.
    - zeven7 4y ago
      This is my real gripe. Let's not pretend "TODO" is the end of the comment.
      - masklinn 4y ago
        Nobody did? The article's goal is clearly to provide a quick categorisation of the TODO, rather than require reading the description to discover it: if I'm trying to debug something and reach a bit of code with a bunch of TODOs it's not going to help me much, if I see a FIXME or BUG I'm going to be a lot more interested. Sometimes the TODO us sufficient through it context (e.g. a docstring empty but for a TODO stanza is obviously a missing doc), but often it's not and is the documentary equivalent of a goto.
bertr4nd 4y ago
My pet peeve is `XXX:`, which I see with distressing regularity in the codebase I work in. It’s non-specific, but vaguely ominous. Is it a TODO? A warning? A bug? An incantation to ward off evil spirits? Tell me!
- mathstuf 4y ago
  I use it with parenthesized clarification. So `# XXX(dependency-version): Reason why we can't have nice things` is code that can be updated when `dependency` of at least `version` can be assumed. The clarification is there so that if the reason itself goes away, we can just remove the conditional. Repeat for things like `cmake-3.23`, `macos-10.14`, `python-3.8` and so on. It's just an easily greppable string and Vim highlights it differently.
- imiric 4y ago
  I use it occasionally as a heads-up about tricky functionality, or to point out something that should be read by future developers, so yes, like a warning. It's similar to `NOTE`, but more important. There's nothing to be done, so `TODO` wouldn't make sense.
  - marcosdumay 4y ago
    Why not `IMPORTANT:`? I haven't seen `XXX:` anywhere, but it's immediately disconcerting as the icon is meaningless. If I have to reach-out to you to discover the meaning of some word you use, it's a bad word.
    - imiric 4y ago
      > Why not `IMPORTANT:`? Like others mentioned, it's not as an established convention as `XXX`. And it's much shorter and quicker to type, particularly convenient when you just want to rant about something, which is the usual use case for `XXX`. ;) At the end of the day, these labels are meaningless unless the entire team is following the same conventions. So using whatever your team agrees with using is the most important thing.
  - 4y ago
guzik 4y ago
No I won't. TODO is much easier to remember than DOCME or TESTME.
jeroenhd 4y ago
I use TODOs liberally while I'm working on a feature branch. When I've figured out a partial solution to the problem at hand, I'll implement that and leave descriptive TODOs wherever necessary. My IDE will warn me about them if I skip them before pushing and simple notImplemented()s will go unnoticed. Sometimes I leave a TODO because a feature/fix must land before a certain date and I don't have the extra time to optimise the code before that. Customers prefer a slow feature over a nonexistent feature. Known bugs can be annotated with a FIXME and an issue number so that nobody will waste time on that part of the code if the bug isn't important enough to be fixed in the current sprint. That said, "TODO: implement" should never ever reach merge requests or code review. Suboptimal implementations may be acceptable, but missing implementations are just bugs or incomplete code.
progx 4y ago
Broke it down to 4 annotations: DEPRECATED:, FIXME:, INFO:, TODO:
genezeta 4y ago
Hmm, in Spanish "todo" literally means "everything"...
- bee_rider 4y ago
  "We've been working on this project for a while, what's left to go?" "Just todo."
- adolph 4y ago
  Yes, just looked this up to confirm my rusty recollection. https://www.collinsdictionary.com/dictionary/spanish-english/todo https://www.collinsdictionary.com/dictionary/spanish-english...
- mLuby 4y ago
  We're not in Kansas anymore TODO fetch ruby slippers
FpUser 4y ago
How about stop telling people what TODO. Especially when the complainer can't even comprehend that TODO can be specialized.
emsy 4y ago
(unless you’re spanish)
dawnerd 4y ago
I use them for when I'm working on code but someone needs me to switch to something else. It's a great way to improve context switching. Otherwise I come back to the code and go, cool where the heck did I leave off.
0xbadcafebee 4y ago
This post reminds me of my new book, titled "You Aren't The Boss Of Me And You Don't Know Me: Stop Telling People What They Need To Do From Your Blog"
deleted 4y ago
[deleted]
cmrdporcupine 4y ago
At some point convention at Google on many teams I was on switched from: TODO(username): blah blah to almost-mandatory: TOOD(bug#): blah blah. Gonna write a TODO? Make a ticket for it, and follow up
- marginalia_nu 4y ago
  I've really liked using a template that looks like this: // TODO ${username} $[date} (ISSUE) - message Having a who and a when is very useful for quickly determining what it's about. The username is helpful for myself for quickly finding my own TODOs, the date is useful for others, as if the issue is so small nobody has bothered fixing it for years, then odds are it's probably not ever going to get fixed and then the TODO can probably be removed.
- erdaniels 4y ago
  been using this approach for a while. it also comes up in PRs to encourage either fixing the issue now, realizing it doesn't need the TODO, or saving it for later. and +1 on searchability when searching ISSUE-XXX and seeing all relevant comments. Would make for a good tool
clintonb 4y ago
I like the concept. IntelliJ IDEs (which I primarily use) recognize both TODO and FIXME by default, and can be configured to recognize other values. Admittedly, I probably won’t adopt these new values since I tend to attach a Jira ticket and a few sentences to many of my TODOs; however, I can see how the concept would help some teams/individuals who tend to be less verbose with their comments.
mr-wendel 4y ago
IMO, I only use three tags: DREAM, FIXME, and HACKS. The whole point is to write less code and better establish when to revisit things. - DREAM tags let me focus on getting things shipped and avoid over optimizing/generalizing things that won't provide immediate value. When working in a professional context, they are always accompanied by a ticket. This adds a nice binding for whoever comes next to pick up the task. - FIXME is also used to help maintain focus, but with the rule that no code ever gets merged with this tag still in place. For personal projects my branches tend to be quite large, so I'm comfortable accumulating some small number of these. - HACKS calls out unintuitive behavior: breaks in abstraction layers, worst-practices that have better implementations than best-practices, or anything that smells "clever". Everything else is just comments that future me/team can look back on and say "he must have been drunk when he wrote this, but thanks to these comments I can clearly understand the context and at least what was intended."
- deleted 4y ago
  [deleted]
- cellularmitosis 4y ago
  I've had good success using a system with two levels of severity: - // STOPSHIP: the presence of this string anywhere in the codebase causes a production build to fail. - // TODO: for everything else.
- qiskit 4y ago
  What about "// TODO !", "// TODO !!", and "// TODO !!!". Where the number of !s indicates the urgency - the more the urgent.
- legorobot 4y ago
  My one tweak would be that in projects in development, the hard rules are less applicable. Sometimes I've found hard-coding some things (e.g. FIXME items) are to make it into production when developing a prototype and testing (< 1.0.0). Once you're reaching 1.0.0, you know these can no longer be sliding through, and you can support all of this in CI.
- epage 4y ago
sod 4y ago
Committed @TODO in code is a junk drawer for people who don't like ticket systems. If you are working alone, sure. But in a team, please show your peers some respect and allow them to prioritize/document todos via a ticket system so a product manager can drop it or assign someone else on it. But don't litter the code with a bunch of TODOs.
kgeist 4y ago
At our company, we have a rule: when you want to add a TODO you must create an issue in the issue tracker (which is added to the backlog) and place the issue ID after the TODO. This way you have a full context/description what was the intent (is it a bug? is it a feature we abandoned for now? is it a temporary hack?) and since it's in the issue tracker you can do all sorts of things such as sort/group by tag, date, priority etc. It's also easy to find all places in the codebase which need to be touched, by searching for the issue ID.
antoineMoPa 4y ago
I try to never merge TODOs in master. I do use these in feature branches, but if it was not important enough to fix while working on a PR and there is no ticket for it, the probability that it ever gets done is low and it ends up cluttering the code. Considering I want to delete my TODOs before I merge, it's much easier to cleanup if it's all the same line prefix (TODO).
nxpnsv 4y ago
If you have so many todo’s you need a syntax to define them more precisely, perhaps use less of them?
marcosdumay 4y ago
Hum... Ok, just standardize those names so we can have tooling support, and make them as fewer as possible so they are easy to remember. Honestly, the article has a very expensive proposition and a completely unsatisfying reasoning. If you want to add some explanation, well, add it after the tag. The tag is exactly that, a tag, not some part of your comment.
mattw2121 4y ago
TODO: add a comment here later
StevePerkins 4y ago
> "If you can’t tell, this isn’t a super serious post. You can easily describe what you want to do in myriad ways using the classic TODO and beyond." HN is one of the best discussion sites out there now, but I wish that we weren't so formulaic and repetitive. So many things get over-pushed, simply due to the familiarity of popular structures such as "X Considered Harmful" or "Why I Don't X". If you actually read this blog post, the thread here is taking this way more seriously than the actual author was.
- tough 4y ago
  And that's why you came to HN for the headlines, but stay for the comment section my friend!
- Bedon292 4y ago
  It feels like the post was meant to spark discussion. Which is has. It doesn't feel like anyone is taking it all that seriously to me. Just discussing what has and hasn't worked for them. I have even learned a few things from it.
- GoldinGuy 4y ago
  You have to include disclaimers like that or else people on the web will come after you. But yeah, the hope was that it would spark some discussion on the topic.
  - StevePerkins 4y ago
    There's not really a lot to discuss. Most tools support automatic aggregation and review of code comments starting with "TODO". Maybe some of these tools can be configured to support other prefixes as well. But they all support "TODO" by default, and it's pretty trivial to just put your shorthand descriptors after the "TODO". Also, if you're pushing commits with a ton of "TODO"'s, then you're probably doing something wrong. Many tools will warn you by default, and many CI/CD pipelines will block your commits altogether. If something is small enough to be addressed right now, then you should address it right now. If it's large enough to require addressing later, then it should be a tracked ticket rather than a loose code comment.
zomglings 4y ago
This article seems to have been written by someone who doesn't use grep. I don't want to remember a complete ontology of greppable signifiers. I would prefer to just 'grep -R "TODO" <dir>' or 'grep -R "TODO(zomglings)" <dir>' than use a more complex grammar as the author suggests. We can stuff those kinds of semantics in the TODO message.
palata 4y ago
To me, TODOs are the equivalent to keeping thousands of tasks in a growing backlog. It just adds noise for stuff that probably won't be addressed ever. And if it is addressed, chances are that it will be from a new task. Just forget it! If it's important, it will come back on its own. I just don't write TODOs in my code, as I have never seen a useful TODO in a codebase... The worst being "TODO: improve this". Sounds like a way to say "I wrote shitty code, I know it, please merge it anyway", which is completely useless IMO.
- haswell 4y ago
  > Sounds like a way to say "I wrote shitty code, I know it, please merge it anyway", which is completely useless IMO. This is not a TODO issue, this is a merge criteria issue. TODO and its variants are only as useful as the process enforced surrounding their use. If a dev team agrees that code can't be merged until certain types of TODO-variants are addressed, then the comment may be useful. But of course, if no such process exists, they may not be useful. But that's a team/process issue, not a fundamental problem with using TODO comments.
AlwaysRock 4y ago
One of my favorite things to do is search a larger codebase for TODO and see what made it into production. I have hopes of one day being a more competent engineer and being able to go squash the todos.
neurotrace 4y ago
I'm a fan of using the extensions the author mentioned when I'm exploring a problem space. I scaffold out the overall design for the problem in terms of modules and functions so that the code reads correctly, type checks, and works for an extreme subset of inputs. Anywhere that I haven't actually implemented the real solution I put in a "NO-MERGE" comment. Then when I feel that I've solved the problem at that scale, I can go through all of my NO-MERGE comments and implement them correctly. As the name implies, these are never merged in to main/master. They just act as bookmarks which should be obvious when reviewing my changes. Personally, I try not to commit any TODO comments. They're sort of like warnings. Unless you're religious about clearing them out, they're just going to build up and be ignored.
ksnll 4y ago
TODOs to me are pretty useless. Usually, they end up lying around for a long while and just create clutter. Opening a ticket is usually much better
shagie 4y ago
The original Java style guide from 1997 defined "FIXME" and "XXX" in section 10.5.4 https://www.oracle.com/technetwork/java/codeconventions-150003.pdf https://www.oracle.com/technetwork/java/codeconventions-1500... > Use XXX in a comment to flag something that is bogus but works. Use FIXME to flag something that is bogus and broken.
overcast 4y ago
Don't tell me what to do! Besides, there is a million other mountains, and battles to die on.
TheRealPomax 4y ago
TODO and FIXME work with my IDE, whereas none of those other words do. So I couldn't care less whether they're suboptimally descriptive: I'm going to keep using TODO for things I need to do, and FIXME for things that are known broken atm, because those are the keywords that automatically get turned into dedicated lists in my editor UI so that I can work with them right in my editor without any additional tooling or mental overhead. And if I need a better description: good news, you don't just write "TODO", you write "TODO: add cyclonavigatory imbobulator to fedonculate the explonizle" and you get to see that text so that it's perfectly clear what the task is. There's literally no need for a different keyword to more specifically bin "the kind of TODOs". One bin for "tasks" and one for "bugs" really is enough. Anything more, and you should start using an issue tracker, not just more keywords. (and ideally all your TODOs are also issues already, of course)
rank0 4y ago
Who cares?
edf13 4y ago
But then we have to remember all the different tags we’ve used! Sometimes months later!!! Search TODO wins
munro 4y ago
I really like this! Though I'm still going precede everything with TODO like so: TODO([person], [subtypes...]) [message] Just as a catch all, in case w/e tool (or other people) don't grok the subtypes of TODO, or in case I encounter a new subtype I'd like to use. And at this point I think TODO is pretty ubiquitous.
Anaminus 4y ago
I WILL use todo for everything! But instead of committing them inline, I will dump them into a TODO file that is ignored by the VCS. If this file starts getting too big, then I'll move some of the long-standing todos out to an issue tracker. > Why not just go straight to the issue tracker? An issue tracker adds a lot of overhead. It's sitting on a different system, so you have to have a separate window open. It's public, so you have to spend time producing a comprehensible issue. Every action is a commitment. Internet access is essential. Meanwhile, TODO is just a file, so it can sit right next to your code. Its private, so you can just stream thoughts right into it and move on. Adding an item is as simple as typing out some lines, and removing that item is as simple as deleting some lines. Need to search? Just grep it. It's fast, and it doesn't leave a mess in your code.
- inferense 4y ago
  would it help having a TODO inline linked to an issue tracker automatically? so you would never have to switch context.
ucarion 4y ago
I'm skeptical of use of TODO in general, because we rarely know what the future portends. To say "TODO" is to assert what must be done in the future, when in reality all we can typically say is "NOTDOING". That said, "TODO" is well-understood by a lot of editors, so it's often useful to just drop that word in the source code to make it easier to find. A more reliable approach is to: 1. File a ticket, and 2. Leave a comment in the code linking to it: // This code does X, but it'd be better to do Y. At the time of writing // fixing this doesn't seem to be an issue worth fixing. // // See: https://bugtracker.example.com/... It's very difficult to write code that correctly predicts the future, but it's easy to write code that accurately describes the status quo at time of writing.
- travisjungroth 4y ago
  > To say "TODO" is to assert what must be done in the future. This isn’t any different from filing a ticket. There’s merit to keeping all of your work in your issue tracker, but this isn’t part of it.
Tainnor 4y ago
I don't get the hate that TODO comments get (edit: in this comment section, not in the original article). They signal that the person who wrote the code has recognised there is a potential issue, has deemed it not relevant enough for it to be solved right now and wants to summarise the issue in the comment. If you disallow TODO comments, you will lose that context, or at least it won't be easily searchable anymore. Issue trackers are not a solution because: - they create too much friction. A developer that is short on time might add two or three comments to suboptimal code rather quickly but would likely not bother dealing with a clunky UI like JIRA, having to write detailed descriptions referencing the exact place of the code, filling out 20 fields and then being hounded by a PM who (rightfully) doesn't understand what "implement foobar() in linear time" or "make Frobulator thread-safe" means. - Comments are right next to the code, issues are not. I see people pointing out that comments can get out of date, but so can issues in an issue tracker. - IMO, "refactoring tickets" tend to be the worst tickets, they're rarely fun to work on, they don't include the context for why the refactoring might be necessary or what the best way to evolve the code is, and if someone else is assigned to the issue than the author of the ticket, they might not even understand the intended refactoring. A comment is much more light-weight and optional and anyone who touches the code can read it and decide whether it makes sense to fix it. It's also almost impossible for a PM to know how to prioritise refactoring tickets. IMHO, unless we're really talking about refactoring entire systems, refactoring should preferably be done continuously whenever the need arises, i.e. "first make the change easy, then make the easy change". - of course, code shouldn't be merged if there are glaring issues that don't implement the feature correctly / could break important things. It's the responsibility of the developer and the reviewer to make sure that this doesn't happen, regardless of whether there are "TODO"s or not.
- deleted 4y ago
  [deleted]
- sdiupIGPWEfh 4y ago
  Hear hear. Dodging an issue tracker is, IMO, one of the clear benefits of TODOs (or FIXME, HACK, BUG, and family). Especially in low-trust teams or whenever there's a need to avoid the sorts of politics that can arise between roles. Refactoring tickets are terrible for all the reasons you point out. PMs will essentially never prioritize refactor work over new features unless pressured to, and if so, the work more often than not gets assigned to newer hires and junior devs, whereas a TODO is actually more likely to get picked up by a curious and intrepid newcomer when they're actually ready for it. Should said newcomer stumble across it before they are ready, it can also be a signal that they ought to reach out to a more experienced developer to ask some questions. For devs, refactor tickets may be useless overhead: in time spent writing, time spent defending, time spent estimating, etc. And in return, there's little glory or praise achieved in working on them; tracking too much time on refactor tickets may even attract negative attention from management. Then good luck if your QAs and agile leads are suspicious of any unit of work that a new test plan can't be written for. A good TODO is sometimes just how the sausage is made.
hk1337 4y ago
@TODO: Stop using TODO
lmc 4y ago
My system has become: TODO (never make it into `main`) SHOULDDO (may have been TODOs in a previous life) COULDDO (effectively pre-emptive strikes for code review) I don't know whether this is a good thing or a bad thing.
- ozim 4y ago
  I really like TESTME from article as pre-emptive strikes for code review :) This way you get all reviewers that write "any unit tests for that" covered and any brogrammer will know it is strong alpha male territory.
Zamicol 4y ago
Docs should be written along with code, while the problem is still fresh in your mind. If there's the need for DOCME, there's possible something wrong with the way a team is writing code.
Ensorceled 4y ago
I use TODO: as a specific type of comment, a message to future developers about stuff to do later that isn't a bug or feature: a) Suggestions for refactoring: TODO: move this to its own class b) Known future work: TODO: remove this when legacy accounts are deleted c) Warnings: TODO: this probably doesn't scale, suggest XXX instead
RazorX 4y ago
My favorite tag is UPSTREAM to annotate workarounds forced by 3rd party libs or otherwise. Normally I include the link to the associated GitHub issue or SO post. Tends to be the most useful in-code comment because if someone comes along and "helps" to refactor the "weird" code, they could accidentally undo the workaround and get stuck in the same loop the original author was in.
fassssst 4y ago
Use a TODO that has a forward link to your issue tracker.
mrbuzzinfrog 4y ago
IMO these are anti-patterns that makes code smelly. A practice I like to follow is to document "hacks" and create tickets for TODO items. In my experience, this has scaled better with the growth of the team and also allows for knowledge sharing and brainstorming when planning. For TODO items I used the "eisenhower matrix" to decide if I should create a ticket for it or not. Where TODO items that are not "urgent" nor "important" are simply ignored until they reemerge again. There are few phrases that I like to mention when I see devs add TODO comments: - if in doubt leave it out - every line of code is a potential liability that needs to be maintain and tested - in the future requirements may be different or no longer relevant
bastijn 4y ago
TODO: implement this system and update all tools to find them in my code base. /JK In our group we have the rule to add a task/story/feature ID when you add a //todo in the code. It helped us to prioritize and close todos. If the task was not prioritized for a long time (became overdue) or was rejected the todo is also removed from code. Apparently it was not deemed important enough to implement it and current code became the accepted version.

235 points by GoldinGuy 4y ago

dfee 4y ago

I have put in many that look like `TODO: can’t foo because bar. workaround with buzz. tracking: github.com/issue/1234` or whatever. Every once in a while I go back through and clean up what I can. I think this is good.

jbverschoor 4y ago

Visual C++ in the '90s already supported all of those..

tonnydourado 4y ago

Ok, but hear me out: what if I don't use any of these, just put ToDo everywhere, and don't waste time thinking in what category the current todo should fall on? Then I book 15 minutes at the end of each day or even week to categorize everything and put into a backlog.

DrBoring 4y ago

I like to use DEBT for times when I'm writing code that I know are poor practices, and will need to be refactored, but I'm in a mood where I just want to get something built that I can see and UI test.

vodou 4y ago

For unimplemented stuff / placeholders I highly recommend exceptions instead of TODOs in any form (if suitable and your language of choice supports that). E.g. in Python: def my_fancy_function(): raise NotImplementedError

TheRealPomax 4y ago
But why only one or the other? The TODO is for your IDE to tap into so you can quickly and easily find outstanding work before the code is ready to be submitted as MR/PR (most IDE and even many simpler code editors have TODO/FIXME listing built in). The exception is for runtime behaviour until the TODO is resolved: it's something you do mostly for yourself, not others. By the time others see your code, your TODOs have either been addressed, or they're acceptance criteria for follow-up work in your project tracker. And that brings us to the third part that we _also_ need: the issue that the work the TODO talks about is for. Either as a checkbox task in a larger piece of work, or if it's big enough, taking up the entire issue. (because good project management means knowing what tasks are required/which work is outstanding, without opening a single file)

yosito 4y ago

I pretty strongly disagree with this. The advantage of using TODO for everything, is that it's easily searchable, and you don't have to try to guess/remember, which labels are used for your comments. If your task is more nuanced than a simple TODO, you can explain in the description after the keyword. The purpose of the keyword is to make it easy to find and take action on in the future, and moving away from using a single keyword makes it easier to miss a comment and harder to take action.

beepbeepnewnew 4y ago
Full agree. They also write > the value of using a broader selection of terms is that you (and therefore all the other programmers you’re collaborating with), are able to be more descriptive about what it is precisely that you need “to do.” But that's what the space after `TODO:` is for. To say what it is you need to do later. The less complexity you add, the less you have to maintain. This mainly applies to things of a certain smaller scale, but I find I encounter `TODO` in my code when I am in a certain scope or just have some free time to refactor, fix things, etc., neither of which require anything beyond a searchable string, as you mentioned. This reminds me of any note taking app that uses #tags. You start in earnest and tag things; you end up with twelve different tags for #cooking, #baking, #food, #recipes, etc. because you forgot which one was which when organizing; it falls into disarray; you are left with unusable cruft, so you end up just searching for "bread" in the search bar, anyway.
- GoldinGuy 4y ago
  That's a totally fair assessment - I can certainly relate with tags in note-taking apps
- shakezula 4y ago
  That exact problem you mention about tag saturation is why I switched entirely to a zettel method where notes are only organized by what they link to or from. Tag structures also just aren’t that great for later recall.
  - 4y ago

OnionBlender 4y ago

I wonder if these types of articles would get a lot less attention if the title was something less assertive like "Consider replacing TODO with something more specific".

GoldinGuy 4y ago
Oh for sure. I've posted on HN plenty of times and never gotten any comments - I post something short and "hot take" and suddenly get top 10 lol

HNHatesUsers 4y ago

inferense 4y ago

would it be valuable for anyone to have an inline TODO / categorised TODO automatically link to an issue tracking tool? I'm building one, and this kind of feedback would be very helpful.

brunoqc 4y ago

There was a tool a while ago that let you track bugs and implementations with comment tag inside your code. I think it sounded like "artifact", but I can't find it. I think it was abandoned, but are there other tools like that?

ThePhysicist 4y ago

Why was the title edited to say the exact opposite of what the article says? This practice seems to get a bit out of hand recently.

GoldinGuy 4y ago
I'm not sure - I didn't edit it and I don't know how to fix it
- mtVessel 4y ago
  HN has some rules for automatically fixing up headlines. Usually it edits out small words like "the" and "a" at the beginning of a title. I have no idea what the rationale for this is, especially considering the potential for corrupting the emphasis of the original headline, like in this case.
maicro 4y ago
I noticed this as well; at first I thought this was a tongue-in-cheek response to the "Stop..." version.
gitgud 4y ago
According to the "HN guidelines" [1] > Otherwise please use the original title, unless it is misleading or linkbait; don't editorialize. So, "Stop using" could be considered "linkbait", which could be why it was changed to just "Using". It's ironic that this has the effect of misleading the author's intent... [1] https://news.ycombinator.com/newsguidelines.html https://news.ycombinator.com/newsguidelines.html

toss1 4y ago

Great idea overall. Rather than entirely replace "TODO" (which would then require multiple searches when a single one now finds all instances), consider augmenting it instead. E.g., TODO-FIX, TODO-DOCUMENT, TODO-ADDFEATURE... (or, if you prefer, abbreviated versions of such tags)

Joeri 4y ago

I don’t think it matters that much how they’re labeled as long as they are easy to get rid of. Before I ship something to production I try to get rid of all TODOs. Sometimes this means rewriting it as documentation of weird behavior, often it means moving it an external backlog, once in a while it is actually doing the TODO. Once a TODO ships, it is effectively a WONTDO because nobody is going to want to touch that hairy code and if it works it works.

Waterluvian 4y ago

To each their own. Mine is: TODO is a linting error and should not exist when it’s final PR time. We use them for our own feature branch dev work. Any item that’s a “do later” needs a URL for a ticket/issue in the comment. These are very rare and discouraged as usually the issue alone is enough. Don’t need to mention it in the code because even the location of the mention can basically be an opinion on how to solve the problem.

MetaWhirledPeas 4y ago

If you have to subcategorize your TODOs you probably have too many TODOs.

bachmeier 4y ago

FYI, the title of the post is "Stop Using TODO For Everything" which is very different from "Using TODO For Everything".

evanmoran 4y ago

If it helps I think of todos as thoughts for future programmers so I try to give more context including category and priority: TODO(security, p1, blocking): login must be authenticated TODO(perf, p3): update can improve to O(n) if needed TODO(data, p1, blocking): this db insert should be retried on failure

oedo 4y ago

HN in 2023: "Conventional Codetags: a specification for structured TODO comments"

j-rom 4y ago

I believe that categorizing comments will save some time down the road if you're specifically looking for something like "BUG". However, searching and aggregating all comments becomes more difficult, which is, in my opinion, one of the main benefits of using "TODO".

foxlisk 4y ago

Why is this link different in a misleading way from the actual title of the blog post? Doesn't HN usually avoid that?

shireboy 4y ago

On productivity hack: I routinely put “//TODO: you are here. (Description)” in the code before I close it for lunch or the day. This way I can pick back up right where I left off. Saves a few mental threads context switching.

Centigonal 4y ago

This is silly to me - not because using multiple tags is better or worse, but because # TODO is something I see as primarily personal shorthand, and I think it's counterproductive to prescribe tags for people to organize their own code with. If my brain likes "TODO: fix edge case" and your brain likes "FIXME: edge case," that's okay. I guess this is relevant if you're using TODOs in the main branch, but I see that as rare. There are very few times I've had someone else pick up a TODO I've written, or vice versa. In my current team, if we're passing a To-Do/bugfix/enhancement to someone, that becomes a ticket and/or a Slack conversation.

soheil 4y ago

Please don't. If you're reading a sentence in a TODO you can decide what it wants you to do, it's bizarre to claim the reader will be less confused if the sentence was merely labeled differently. This reminds of using emojis in Github issues instead of using a universal up/down vote to count the usefulness of an answer like Stackoverflow. Please don't ruin programming further.

xyzzy_plugh 4y ago

Just going to pick a single nit. > you don’t want your project to end up like the Linux codebase with 3000+ TODOs dating back over a decade. Why don't I? TODOs capture a lot of context that would otherwise be inappropriate or unseen in a comment. They're in all caps and they stand out and draw the reader's eye. They can be completely out of context, whereas comments are typically extremely contextual. They often help explain cases not covered, paths not supported, missing functionality or notes for future contributors. Splitting them into even more comments just makes them harder to find and reason about. When you're writing a TODO, you don't want to stop to smell the roses, thinking about what the future may hold, you just want to blot down the thought in your head and finish the task at hand. Not to mention that in reality it's quite reasonable: https://livegrep.com/search/linux?q=TODO&fold_case=false&regex=false&context=true https://livegrep.com/search/linux?q=TODO&fold_case=false&reg... You be the judge.

chapliboy 4y ago

Right now, I just use TODO along with a description. But the thing that has helped me and my teams most is adding a date and a name to each todo. For example, // TODO (03 May 2022 chap): This can be optimised. The date really helps because many times the TODO was written for an earlier design, and the todos haven't been updated. Many times a lot of time has been saved when trying to figure out the context of a todo. Same for author. Helps to know who made the note, in case any additional context is needed. Though often it is you who made the comment and you've obviously forgotten...

NateEag 4y ago
If you're using a decent version control system, the name and date can be skipped in favor of a quick blame when you actually need to know.
- chapliboy 4y ago
  I guess that's another way to go about it. I don't know how git deals with reindenting, refactoring etc, and you might lose context, but you could probably find it again. It's kinda nice having it right there in the code though.
  - NateEag 4y ago
    I use an iterative blame tool (magit-blame in Emacs) and it generally does pretty well for me. I prefer having the author out of the way and looking it up when I'm curious. I can see how others might prefer the opposite.

Xen0byte 4y ago

I would strongly argue against this. Not only TODO is easily searchable as others have also pointed out, but also in some IDEs you can open a TODOs window which will aggregate all of these so that you can easily keep track of them (e.g. Visual Studio).

dobrinov 4y ago

I would say “Don’t use TODOs (in your code) at all”. They are just “broken windows” in your code. If something is a bug and you think that it is important to be fixed - just do it. If you think that something has to be done but it is out of the scope of your current task, note it down somewhere and take ownership of making it happen one way or another. Leaving a comment in your code just puts this responsibility away from you. In my experience this does not work and those type of tasks just pile up.

spacemanmatt 4y ago

Ok but my tooling defaults recognize TODO and I have many pending deaths on other hills of higher precedence.

ezekiel68 4y ago
Yeah? Well, this is why Jedis do not get their light sabers from Acme Megacorp.
philote 4y ago
Exactly. Plus if I want to find things to fix in my code, searching for TODO is much easier than searching for each of a dozen or so other strings.
- PrimeDirective 4y ago
  And I can add additional information next to the todo: // todo: todo
  - bee_rider 4y ago
    As long as the second todo is also standardized (TODO: FIXME), so it will play nicely with grep.
  - zeven7 4y ago
    This is my real gripe. Let's not pretend "TODO" is the end of the comment.
    - masklinn 4y ago
      Nobody did? The article's goal is clearly to provide a quick categorisation of the TODO, rather than require reading the description to discover it: if I'm trying to debug something and reach a bit of code with a bunch of TODOs it's not going to help me much, if I see a FIXME or BUG I'm going to be a lot more interested. Sometimes the TODO us sufficient through it context (e.g. a docstring empty but for a TODO stanza is obviously a missing doc), but often it's not and is the documentary equivalent of a goto.

bertr4nd 4y ago

My pet peeve is `XXX:`, which I see with distressing regularity in the codebase I work in. It’s non-specific, but vaguely ominous. Is it a TODO? A warning? A bug? An incantation to ward off evil spirits? Tell me!

mathstuf 4y ago
I use it with parenthesized clarification. So `# XXX(dependency-version): Reason why we can't have nice things` is code that can be updated when `dependency` of at least `version` can be assumed. The clarification is there so that if the reason itself goes away, we can just remove the conditional. Repeat for things like `cmake-3.23`, `macos-10.14`, `python-3.8` and so on. It's just an easily greppable string and Vim highlights it differently.
imiric 4y ago
I use it occasionally as a heads-up about tricky functionality, or to point out something that should be read by future developers, so yes, like a warning. It's similar to `NOTE`, but more important. There's nothing to be done, so `TODO` wouldn't make sense.
- marcosdumay 4y ago
  Why not `IMPORTANT:`? I haven't seen `XXX:` anywhere, but it's immediately disconcerting as the icon is meaningless. If I have to reach-out to you to discover the meaning of some word you use, it's a bad word.
  - imiric 4y ago
    > Why not `IMPORTANT:`? Like others mentioned, it's not as an established convention as `XXX`. And it's much shorter and quicker to type, particularly convenient when you just want to rant about something, which is the usual use case for `XXX`. ;) At the end of the day, these labels are meaningless unless the entire team is following the same conventions. So using whatever your team agrees with using is the most important thing.
- 4y ago

guzik 4y ago

No I won't. TODO is much easier to remember than DOCME or TESTME.

jeroenhd 4y ago

I use TODOs liberally while I'm working on a feature branch. When I've figured out a partial solution to the problem at hand, I'll implement that and leave descriptive TODOs wherever necessary. My IDE will warn me about them if I skip them before pushing and simple notImplemented()s will go unnoticed. Sometimes I leave a TODO because a feature/fix must land before a certain date and I don't have the extra time to optimise the code before that. Customers prefer a slow feature over a nonexistent feature. Known bugs can be annotated with a FIXME and an issue number so that nobody will waste time on that part of the code if the bug isn't important enough to be fixed in the current sprint. That said, "TODO: implement" should never ever reach merge requests or code review. Suboptimal implementations may be acceptable, but missing implementations are just bugs or incomplete code.

progx 4y ago

Broke it down to 4 annotations: DEPRECATED:, FIXME:, INFO:, TODO:

genezeta 4y ago

Hmm, in Spanish "todo" literally means "everything"...

bee_rider 4y ago
"We've been working on this project for a while, what's left to go?" "Just todo."
adolph 4y ago
Yes, just looked this up to confirm my rusty recollection. https://www.collinsdictionary.com/dictionary/spanish-english/todo https://www.collinsdictionary.com/dictionary/spanish-english...
mLuby 4y ago
We're not in Kansas anymore TODO fetch ruby slippers

FpUser 4y ago

How about stop telling people what TODO. Especially when the complainer can't even comprehend that TODO can be specialized.

emsy 4y ago

(unless you’re spanish)

dawnerd 4y ago

I use them for when I'm working on code but someone needs me to switch to something else. It's a great way to improve context switching. Otherwise I come back to the code and go, cool where the heck did I leave off.

0xbadcafebee 4y ago

This post reminds me of my new book, titled "You Aren't The Boss Of Me And You Don't Know Me: Stop Telling People What They Need To Do From Your Blog"

deleted 4y ago

[deleted]

cmrdporcupine 4y ago

At some point convention at Google on many teams I was on switched from: TODO(username): blah blah to almost-mandatory: TOOD(bug#): blah blah. Gonna write a TODO? Make a ticket for it, and follow up

marginalia_nu 4y ago
I've really liked using a template that looks like this: // TODO ${username} $[date} (ISSUE) - message Having a who and a when is very useful for quickly determining what it's about. The username is helpful for myself for quickly finding my own TODOs, the date is useful for others, as if the issue is so small nobody has bothered fixing it for years, then odds are it's probably not ever going to get fixed and then the TODO can probably be removed.
erdaniels 4y ago
been using this approach for a while. it also comes up in PRs to encourage either fixing the issue now, realizing it doesn't need the TODO, or saving it for later. and +1 on searchability when searching ISSUE-XXX and seeing all relevant comments. Would make for a good tool

clintonb 4y ago

I like the concept. IntelliJ IDEs (which I primarily use) recognize both TODO and FIXME by default, and can be configured to recognize other values. Admittedly, I probably won’t adopt these new values since I tend to attach a Jira ticket and a few sentences to many of my TODOs; however, I can see how the concept would help some teams/individuals who tend to be less verbose with their comments.

mr-wendel 4y ago

IMO, I only use three tags: DREAM, FIXME, and HACKS. The whole point is to write less code and better establish when to revisit things. - DREAM tags let me focus on getting things shipped and avoid over optimizing/generalizing things that won't provide immediate value. When working in a professional context, they are always accompanied by a ticket. This adds a nice binding for whoever comes next to pick up the task. - FIXME is also used to help maintain focus, but with the rule that no code ever gets merged with this tag still in place. For personal projects my branches tend to be quite large, so I'm comfortable accumulating some small number of these. - HACKS calls out unintuitive behavior: breaks in abstraction layers, worst-practices that have better implementations than best-practices, or anything that smells "clever". Everything else is just comments that future me/team can look back on and say "he must have been drunk when he wrote this, but thanks to these comments I can clearly understand the context and at least what was intended."

deleted 4y ago
[deleted]
cellularmitosis 4y ago
I've had good success using a system with two levels of severity: - // STOPSHIP: the presence of this string anywhere in the codebase causes a production build to fail. - // TODO: for everything else.
qiskit 4y ago
What about "// TODO !", "// TODO !!", and "// TODO !!!". Where the number of !s indicates the urgency - the more the urgent.
legorobot 4y ago
My one tweak would be that in projects in development, the hard rules are less applicable. Sometimes I've found hard-coding some things (e.g. FIXME items) are to make it into production when developing a prototype and testing (< 1.0.0). Once you're reaching 1.0.0, you know these can no longer be sliding through, and you can support all of this in CI.
epage 4y ago

sod 4y ago

Committed @TODO in code is a junk drawer for people who don't like ticket systems. If you are working alone, sure. But in a team, please show your peers some respect and allow them to prioritize/document todos via a ticket system so a product manager can drop it or assign someone else on it. But don't litter the code with a bunch of TODOs.

kgeist 4y ago

At our company, we have a rule: when you want to add a TODO you must create an issue in the issue tracker (which is added to the backlog) and place the issue ID after the TODO. This way you have a full context/description what was the intent (is it a bug? is it a feature we abandoned for now? is it a temporary hack?) and since it's in the issue tracker you can do all sorts of things such as sort/group by tag, date, priority etc. It's also easy to find all places in the codebase which need to be touched, by searching for the issue ID.

antoineMoPa 4y ago

I try to never merge TODOs in master. I do use these in feature branches, but if it was not important enough to fix while working on a PR and there is no ticket for it, the probability that it ever gets done is low and it ends up cluttering the code. Considering I want to delete my TODOs before I merge, it's much easier to cleanup if it's all the same line prefix (TODO).

nxpnsv 4y ago

If you have so many todo’s you need a syntax to define them more precisely, perhaps use less of them?

marcosdumay 4y ago

Hum... Ok, just standardize those names so we can have tooling support, and make them as fewer as possible so they are easy to remember. Honestly, the article has a very expensive proposition and a completely unsatisfying reasoning. If you want to add some explanation, well, add it after the tag. The tag is exactly that, a tag, not some part of your comment.

mattw2121 4y ago

TODO: add a comment here later

StevePerkins 4y ago

> "If you can’t tell, this isn’t a super serious post. You can easily describe what you want to do in myriad ways using the classic TODO and beyond." HN is one of the best discussion sites out there now, but I wish that we weren't so formulaic and repetitive. So many things get over-pushed, simply due to the familiarity of popular structures such as "X Considered Harmful" or "Why I Don't X". If you actually read this blog post, the thread here is taking this way more seriously than the actual author was.

tough 4y ago
And that's why you came to HN for the headlines, but stay for the comment section my friend!
Bedon292 4y ago
It feels like the post was meant to spark discussion. Which is has. It doesn't feel like anyone is taking it all that seriously to me. Just discussing what has and hasn't worked for them. I have even learned a few things from it.
GoldinGuy 4y ago
You have to include disclaimers like that or else people on the web will come after you. But yeah, the hope was that it would spark some discussion on the topic.
- StevePerkins 4y ago
  There's not really a lot to discuss. Most tools support automatic aggregation and review of code comments starting with "TODO". Maybe some of these tools can be configured to support other prefixes as well. But they all support "TODO" by default, and it's pretty trivial to just put your shorthand descriptors after the "TODO". Also, if you're pushing commits with a ton of "TODO"'s, then you're probably doing something wrong. Many tools will warn you by default, and many CI/CD pipelines will block your commits altogether. If something is small enough to be addressed right now, then you should address it right now. If it's large enough to require addressing later, then it should be a tracked ticket rather than a loose code comment.

zomglings 4y ago

This article seems to have been written by someone who doesn't use grep. I don't want to remember a complete ontology of greppable signifiers. I would prefer to just 'grep -R "TODO" <dir>' or 'grep -R "TODO(zomglings)" <dir>' than use a more complex grammar as the author suggests. We can stuff those kinds of semantics in the TODO message.

palata 4y ago

To me, TODOs are the equivalent to keeping thousands of tasks in a growing backlog. It just adds noise for stuff that probably won't be addressed ever. And if it is addressed, chances are that it will be from a new task. Just forget it! If it's important, it will come back on its own. I just don't write TODOs in my code, as I have never seen a useful TODO in a codebase... The worst being "TODO: improve this". Sounds like a way to say "I wrote shitty code, I know it, please merge it anyway", which is completely useless IMO.

haswell 4y ago
> Sounds like a way to say "I wrote shitty code, I know it, please merge it anyway", which is completely useless IMO. This is not a TODO issue, this is a merge criteria issue. TODO and its variants are only as useful as the process enforced surrounding their use. If a dev team agrees that code can't be merged until certain types of TODO-variants are addressed, then the comment may be useful. But of course, if no such process exists, they may not be useful. But that's a team/process issue, not a fundamental problem with using TODO comments.

AlwaysRock 4y ago

One of my favorite things to do is search a larger codebase for TODO and see what made it into production. I have hopes of one day being a more competent engineer and being able to go squash the todos.

neurotrace 4y ago

I'm a fan of using the extensions the author mentioned when I'm exploring a problem space. I scaffold out the overall design for the problem in terms of modules and functions so that the code reads correctly, type checks, and works for an extreme subset of inputs. Anywhere that I haven't actually implemented the real solution I put in a "NO-MERGE" comment. Then when I feel that I've solved the problem at that scale, I can go through all of my NO-MERGE comments and implement them correctly. As the name implies, these are never merged in to main/master. They just act as bookmarks which should be obvious when reviewing my changes. Personally, I try not to commit any TODO comments. They're sort of like warnings. Unless you're religious about clearing them out, they're just going to build up and be ignored.

ksnll 4y ago

TODOs to me are pretty useless. Usually, they end up lying around for a long while and just create clutter. Opening a ticket is usually much better

shagie 4y ago

The original Java style guide from 1997 defined "FIXME" and "XXX" in section 10.5.4 https://www.oracle.com/technetwork/java/codeconventions-150003.pdf https://www.oracle.com/technetwork/java/codeconventions-1500... > Use XXX in a comment to flag something that is bogus but works. Use FIXME to flag something that is bogus and broken.

overcast 4y ago

Don't tell me what to do! Besides, there is a million other mountains, and battles to die on.

TheRealPomax 4y ago

TODO and FIXME work with my IDE, whereas none of those other words do. So I couldn't care less whether they're suboptimally descriptive: I'm going to keep using TODO for things I need to do, and FIXME for things that are known broken atm, because those are the keywords that automatically get turned into dedicated lists in my editor UI so that I can work with them right in my editor without any additional tooling or mental overhead. And if I need a better description: good news, you don't just write "TODO", you write "TODO: add cyclonavigatory imbobulator to fedonculate the explonizle" and you get to see that text so that it's perfectly clear what the task is. There's literally no need for a different keyword to more specifically bin "the kind of TODOs". One bin for "tasks" and one for "bugs" really is enough. Anything more, and you should start using an issue tracker, not just more keywords. (and ideally all your TODOs are also issues already, of course)

rank0 4y ago

Who cares?

edf13 4y ago

But then we have to remember all the different tags we’ve used! Sometimes months later!!! Search TODO wins

munro 4y ago

I really like this! Though I'm still going precede everything with TODO like so: TODO([person], [subtypes...]) [message] Just as a catch all, in case w/e tool (or other people) don't grok the subtypes of TODO, or in case I encounter a new subtype I'd like to use. And at this point I think TODO is pretty ubiquitous.

Anaminus 4y ago

I WILL use todo for everything! But instead of committing them inline, I will dump them into a TODO file that is ignored by the VCS. If this file starts getting too big, then I'll move some of the long-standing todos out to an issue tracker. > Why not just go straight to the issue tracker? An issue tracker adds a lot of overhead. It's sitting on a different system, so you have to have a separate window open. It's public, so you have to spend time producing a comprehensible issue. Every action is a commitment. Internet access is essential. Meanwhile, TODO is just a file, so it can sit right next to your code. Its private, so you can just stream thoughts right into it and move on. Adding an item is as simple as typing out some lines, and removing that item is as simple as deleting some lines. Need to search? Just grep it. It's fast, and it doesn't leave a mess in your code.

inferense 4y ago
would it help having a TODO inline linked to an issue tracker automatically? so you would never have to switch context.

ucarion 4y ago

I'm skeptical of use of TODO in general, because we rarely know what the future portends. To say "TODO" is to assert what must be done in the future, when in reality all we can typically say is "NOTDOING". That said, "TODO" is well-understood by a lot of editors, so it's often useful to just drop that word in the source code to make it easier to find. A more reliable approach is to: 1. File a ticket, and 2. Leave a comment in the code linking to it: // This code does X, but it'd be better to do Y. At the time of writing // fixing this doesn't seem to be an issue worth fixing. // // See: https://bugtracker.example.com/... It's very difficult to write code that correctly predicts the future, but it's easy to write code that accurately describes the status quo at time of writing.

travisjungroth 4y ago
> To say "TODO" is to assert what must be done in the future. This isn’t any different from filing a ticket. There’s merit to keeping all of your work in your issue tracker, but this isn’t part of it.

Tainnor 4y ago

I don't get the hate that TODO comments get (edit: in this comment section, not in the original article). They signal that the person who wrote the code has recognised there is a potential issue, has deemed it not relevant enough for it to be solved right now and wants to summarise the issue in the comment. If you disallow TODO comments, you will lose that context, or at least it won't be easily searchable anymore. Issue trackers are not a solution because: - they create too much friction. A developer that is short on time might add two or three comments to suboptimal code rather quickly but would likely not bother dealing with a clunky UI like JIRA, having to write detailed descriptions referencing the exact place of the code, filling out 20 fields and then being hounded by a PM who (rightfully) doesn't understand what "implement foobar() in linear time" or "make Frobulator thread-safe" means. - Comments are right next to the code, issues are not. I see people pointing out that comments can get out of date, but so can issues in an issue tracker. - IMO, "refactoring tickets" tend to be the worst tickets, they're rarely fun to work on, they don't include the context for why the refactoring might be necessary or what the best way to evolve the code is, and if someone else is assigned to the issue than the author of the ticket, they might not even understand the intended refactoring. A comment is much more light-weight and optional and anyone who touches the code can read it and decide whether it makes sense to fix it. It's also almost impossible for a PM to know how to prioritise refactoring tickets. IMHO, unless we're really talking about refactoring entire systems, refactoring should preferably be done continuously whenever the need arises, i.e. "first make the change easy, then make the easy change". - of course, code shouldn't be merged if there are glaring issues that don't implement the feature correctly / could break important things. It's the responsibility of the developer and the reviewer to make sure that this doesn't happen, regardless of whether there are "TODO"s or not.

deleted 4y ago
[deleted]
sdiupIGPWEfh 4y ago
Hear hear. Dodging an issue tracker is, IMO, one of the clear benefits of TODOs (or FIXME, HACK, BUG, and family). Especially in low-trust teams or whenever there's a need to avoid the sorts of politics that can arise between roles. Refactoring tickets are terrible for all the reasons you point out. PMs will essentially never prioritize refactor work over new features unless pressured to, and if so, the work more often than not gets assigned to newer hires and junior devs, whereas a TODO is actually more likely to get picked up by a curious and intrepid newcomer when they're actually ready for it. Should said newcomer stumble across it before they are ready, it can also be a signal that they ought to reach out to a more experienced developer to ask some questions. For devs, refactor tickets may be useless overhead: in time spent writing, time spent defending, time spent estimating, etc. And in return, there's little glory or praise achieved in working on them; tracking too much time on refactor tickets may even attract negative attention from management. Then good luck if your QAs and agile leads are suspicious of any unit of work that a new test plan can't be written for. A good TODO is sometimes just how the sausage is made.

hk1337 4y ago

@TODO: Stop using TODO

lmc 4y ago

My system has become: TODO (never make it into `main`) SHOULDDO (may have been TODOs in a previous life) COULDDO (effectively pre-emptive strikes for code review) I don't know whether this is a good thing or a bad thing.

ozim 4y ago
I really like TESTME from article as pre-emptive strikes for code review :) This way you get all reviewers that write "any unit tests for that" covered and any brogrammer will know it is strong alpha male territory.

Zamicol 4y ago

Docs should be written along with code, while the problem is still fresh in your mind. If there's the need for DOCME, there's possible something wrong with the way a team is writing code.

Ensorceled 4y ago

I use TODO: as a specific type of comment, a message to future developers about stuff to do later that isn't a bug or feature: a) Suggestions for refactoring: TODO: move this to its own class b) Known future work: TODO: remove this when legacy accounts are deleted c) Warnings: TODO: this probably doesn't scale, suggest XXX instead

RazorX 4y ago

My favorite tag is UPSTREAM to annotate workarounds forced by 3rd party libs or otherwise. Normally I include the link to the associated GitHub issue or SO post. Tends to be the most useful in-code comment because if someone comes along and "helps" to refactor the "weird" code, they could accidentally undo the workaround and get stuck in the same loop the original author was in.

fassssst 4y ago

Use a TODO that has a forward link to your issue tracker.

mrbuzzinfrog 4y ago

IMO these are anti-patterns that makes code smelly. A practice I like to follow is to document "hacks" and create tickets for TODO items. In my experience, this has scaled better with the growth of the team and also allows for knowledge sharing and brainstorming when planning. For TODO items I used the "eisenhower matrix" to decide if I should create a ticket for it or not. Where TODO items that are not "urgent" nor "important" are simply ignored until they reemerge again. There are few phrases that I like to mention when I see devs add TODO comments: - if in doubt leave it out - every line of code is a potential liability that needs to be maintain and tested - in the future requirements may be different or no longer relevant

bastijn 4y ago

TODO: implement this system and update all tools to find them in my code base. /JK In our group we have the rule to add a task/story/feature ID when you add a //todo in the code. It helped us to prioritize and close todos. If the task was not prioritized for a long time (became overdue) or was rejected the todo is also removed from code. Apparently it was not deemed important enough to implement it and current code became the accepted version.