Hacker News Reader

Comment by war1025 | Hacker News Reader

In my opinion, any comment prefixed by TODO, XXX, or the like should not survive past the review stage. Either fix the problem immediately or accept that it's going to be wonky forever.

Edit:

Amending here to avoid replying to ten different threads individually.

1. Long-term improvements should be managed by a ticket tracking system. The code is not the correct place to manage that.

2. Most of the disagreements below seem to come down to nomenclature differences.

In my own work, the code is liberally sprinkled with "Note:"s. These are, as others have pointed out, useful for providing context of what is going on, why, how it is non-optimal, etc.

TODOs that I come across tend to be of the "You ain't gonna need it" variety. If you can get a pull through review as-is, then the thing wasn't actually a "TODO", and if it was, then it should be added as a ticket to the backlog.

XXXs tend to show up in the reviews I do as code that is explicitly meant to be fixed before the pull is merged.

So to summarize:

1. "Note:"s in code are great.

2. "XXX" shouldn't survive the review

3. "TODO" should be handled by the ticketing backlog to better separate out "actually needed" from "theoretically nice, but not necessary in practice".

Further, things that are "TODO" today often make zero sense as "TODO" in a year when the code has grown and evolved more, but since someone put it in as a TODO, I find that they rarely ever get removed since "surely someone knows what that means" (but that person is usually either gone or no longer remembers).

View on HN

That's a terrible advice. When I worked at Google, many code reviews added more TODOs because the reviewer identified a potential source of problem but also correctly decided that fixing it right there was not the best use of developers' time.

When code has potential issues, I want it to be marked with TODO which basically says "The original developer was not an idiot, but was working with limited resource and the best way to fix the issue wasn't clear then."

> That's a terrible advice. When I worked at Google, many code reviews added more TODOs because the reviewer identified a potential source of problem but also correctly decided that fixing it right there was not the best use of developers' time.

I'm sure Google is able to adopt a working ticketing system. If you already have an issue tracker then it makes absolutely no sense to keep a separate out-of-band ticketing repository such as source code sprinkled with TODO entries.

> When code has potential issues, I want it to be marked with TODO which basically says "The original developer was not an idiot, but was working with limited resource and the best way to fix the issue wasn't clear then."

That makes absolutely no sense at all, unless your goal is to simultaneously avoid accountability, poopoo other people's work, and actually do nothing to fix the problem.

From the point of view of being in the middle of working with some piece of code, it's the issue tracker that's out-of-band! Also, a lot of those TODO entries tend to not be good entries into issue tracker (do you want to track "add extra error checks foobar at line 213 in quux.c"), and they tend to be very localized to the area of code they're left in - which means that, unless your issue tracker supports some way of encoding coordinates in files that survives changes to those files, future people modifying a piece of code are very unlikely to see those notes if they're not left in the code itself.

The counter-argument would be that if it's work, and it needs to be scheduled (which is what we're talking about here) then it needs to be tracked wherever all the rest of the work is, so that it can be made visible and prioritised alongside everything else.

The "how do I encode a link to code that doesn't go stale" solution is to use a link to the source code repo browser which points to a specific time and place - don't point at `master`, point at the specific revision hash you're talking about.

Linking to revision doesn't help in the context of our discussion - it still doesn't solve the problem of automatically getting that information inline with the code at the correct place in the file, for the correct time (if it would show up only in the linked revision then it would be useless; if it would be inherited by future revisions, then how do you delete the annotation once it isn't needed anymore?).

As for tracking work, these kind of comment notes are about units of work small enough that tracking them would be very counterproductive for the company. This would be extreme level of micromanagement.

There is a pretty simple rule for this problem:

Can you do it immediately? Do it now. Must you do it later? Write it down.

If you decide to use TODO as a way of writing something down then you must make sure that these TODOs are just as visible as whatever ticket system you're using and that they are integrated into your release schedule.

I disagree. The reason those TODOs appear is because the answer to the question "Can you do it immediately?" is, "yes, I can, but it would break my flow and interrupt what I'm doing right now". The reason some of them don't later get promoted to issues in the tracker is because they're too small or otherwise irrelevant at the project level. Their place is in the code, where the next person looking at it will spot them.

Then it is not a TODO, it is a NOTE. Don't act as if it will be _done_ magically in the future. If I stumble upon a TODO, I won't fix it (because it will diasrupt my flow - the reason for the TODO in the first place). And if it is not in the issue tracker, I can't plan for it. A solution would be some kind of an "implement as many TODOs as possible" time-boxed spike, but this never worked really well for me in the past.

>I'm sure Google is able to adopt a working ticketing system. If you already have an issue tracker then it makes absolutely no sense to keep a separate out-of-band ticketing repository such as source code sprinkled with TODO entries.

If I'm on another team looking at using your code for whatever reason, I may not be familiar with your ticketing system, what is where, how it's organized and prioritized, etc. I appreciate an indication in the code that that function or class might have some significant areas for improvement. If it's relevant enough to what I'm doing, maybe I'll handle the TODO and open up a code review for your team. Ideally you've got a TODO with some details and also a ticket I can reference to see what's going on with it or what discussion has already occurred around it.

But companies of FAANG size often have so many different developers on totally different teams that they're probably not going to have the time or inclination to go look through your ticket backlog. Having any deficiencies or areas for improvement clearly marked in the code is a benefit in those situations.

This completely negates the cost of context switching. Not all of us are superhuman multitaskers.

I don't think anyone's saying that any time you encounter something which needs fixing you should drop your current work, open up the ticketing system and type out a detailed description there. It's just that the TODO comments shouldn't be part of your final commit (or equivalent).

Think of it like those little `print(f"foo is {foo}")` statements you add or the code you comment out while debugging - you use them to quickly develop piece of functionality, then you back them out before `git commit`. This is the point where you'd collect them together and create the tickets - your local work is "done" and you're doing a final review.

That's a fair point!

Edit: No I thought about it, and I changed my mind again. The TODO comments are primarily for the benefit of the subsequent readers, so they're not having to do so much exegesis and assorted WTFing. If you only have that info in the issue tracker, it's only available to the person dealing with that issue, not the people who have to deal with that code in the course of other maintenance.

In recent years at Google a rule was adopted that TODO should be followed by a bug number or not be put in at all.

> I'm sure Google is able to adopt a working ticketing system. If you already have an issue tracker then it makes absolutely no sense to keep a separate out-of-band ticketing repository such as source code sprinkled with TODO entries.

We don't need any comments, then, if we have documentation. Right?

My point is they're not the same thing and don't serve the same purpose. A TODO comment is not the same thing as an issue. The audience is, or should be, different, as is the context.

I'd rather not lose context of what I'm working on by switching from code to issue tracker. That's how bugs are born.

Exactly.

TODOs should be an adjunct to the issue tracker. An issue could be "Clean up/resolve all TODOs in module qux". but each of those comments on there own are rarely worth the issue on their own.

Also not every project has the FTEs or the scope to hit every TODO in the first pass. Maybe it's all a glorified demo and these are "Road closed" points to be enhanced/hooked in to in the future.

> An issue could be "Clean up/resolve all TODOs in module qux". but each of those comments on there own are rarely worth the issue on their own.

In my experience, this doesn't work. How many story points does it take to solve _all_ TODOs in a module? How many modules are there? How do I explain this task to a manager or stakeholder? How do you handle TODOs that you think are nice-to-haves or even unnecessary (while your collegue may disagree)? What about TODOs that you do not unserstand (because it is often a one-liner). All those points are mostly solved by 1. Extracting important issues into a ticket OR 2. Commenting the code with a NOTE (instead of TODO), admitting it is not cost-effective to implement. The comment is there as an info for future developers, but it does not look like task that just waits to be implemented.

I've been in many scenarios where fixing a certain behavior or implementing something in an optimal way requires a change in an external or upstream product. Or it may require a larger refactoring that's in discussion or otherwise outside the scope of the quick fix. "Either fix the problem immediately or accept that it's going to be wonky forever," sounds like a nice ideal but it's not practical to treat it as an absolute.

What I usually do is link the TODO with the associated Github issue/bug tracker (in the commit message too, so it shows up as a reference) to avoid the TODO being forgotten when its blocker is resolved.

Yep, the todo is there to indicate to future code readers that yes we know this sucks but can't fix it properly yet because of blocker X, so don't try to make a half-assed fix yourself without consulting issue tracker nr ### first.

See it as an index into the issue tracker so you don't have to search the issue tracker any time you come across some really strange code. This could of course be done with normal comments also, not necessarily todo.

Disagree. There are lots of reasons TODOs live on, mostly having to do with stashing ideas that aren’t functionally critical, or pointers for future devs who might inherit the codebase without immediately grokking a performance optimization or corner case that occurred to the previous owner, but wasn’t important enough to deal with at that time. Sometimes, they just save face for the original dev who would love to make something better, but had to move.

Black-and-white rules like “No TODOs after review!!” are not only too trivial to enforce for a real production team working on deadline, they remove the soft fuzzy subjective edges that make what we do art, not math.

What's the advantage of throwing away context that could be useful in the future? I've taken ownership of codebases with technical debt before, and when modifying the code for something time-sensitive, I often annotate issues with the code whose solutions (usually refactoring) can't be fit into the timeline of the current project. I (or others) can then take advantage of these annotations when I have time to dedicate to refactoring, or in many cases, fit the refactoring into feature work. The fact that a portion of the design groundwork has already been done (as captured by the TODO) makes it easier to fit in the cleanup work. IME, this approach leads to much more rapid improvement of legacy codebases than your description of do-it-now-or-forget-about-it.

You don't throw it away, you put it in the issue tracker where it can be prioritized, tracked and categorized. If it's not worth of the issue tracker, it shouldn't be worth of a TODO either.

Eh. This is a company culture thing that depends on how you use your tracker.

At many companies, issue trackers are not used for things like "refactor this method". They're used for user-facing stories or architectural projects, and they're transparent to managers who don't want them cluttered with non-user facing stories.

I've run into managers who didn't want any TODOs in code, they wanted everything to go through the tracker. I've also run into managers that told me to stop putting everything into the tracker because they didn't know how to prioritize a random method refactor, and they felt like that information wasn't relevant to their scheduling.

I don't have a strong preference, but I lightly lean towards preferring the latter strategy. Issue trackers are slow. They are so slow, and so cumbersome, and so hard to organize, and you waste so much time linking to code files that get refactored or moved around so the context is lost. The nice thing about a TODO in code is if the method gets deleted, the TODO also gets deleted. When you're refactoring code, you don't have to go search an issue tracker and think, "wait, is there anything related to this refactor I need to update?"

If documentation is code that never gets compiled, issue trackers are like dynamically linked libraries that never actually get compiled or linked. It's very hard to keep them up-to-date; it's very hard to preserve the references.

For smaller, single-person independent projects, I don't use issue trackers. I use high-level todo lists, and all of my notes are in code next to the context they're being used for. This is because an issue tracker is just bloat for those kinds of projects.

I think it's less of a company culture thing and more of a local team preference thing. If the ICs on a team are united, managers are often willing to change things a bit from how they're used to it. It could be just as simple as prefixing a "[Trust]" tag to items that are important and have some priority within developer minds, but product management has no opinion / ability to form an opinion apart from earlier they've agreed on a general "[Trust]" bucket to account for such things. This lets them be filtered out as needed. Worst case, a united team can have a private issue tracker and beef up their estimates to management to account for work management doesn't want to hear about but needs doing nonetheless.

If you don't have either a united team or managers willing to move at all, or even work with ICs collaboratively, you have bigger problems than what you do with TODO et al. If I were in such a situation I'd still use an 'issue tracker' (maybe a local text file) 9 times out of 10, while also looking for a better job.

Issue trackers are slow and I have to work with one of the slowest (it was built in-house on top of a core product never meant for such a thing...) but some are much faster than others. Command line ones can be pretty slick. Still, it comes down to team (and individual) preference and experience (your "very hard"s are never even "hard" in my experience). Even on a personal project that's going to span a decent length of time, I'll take the slowness of adding even a minor issue and the rare risk of grooming/popping the backlog (and all this might just be in a single local text file, very low overhead) only to discover an item no longer applies and taking the second to Never it. It's not only faster for me in the long run but maximizes the incentives for the things I want in a system that I'm tasked with maintaining and improving.

Coupling it to the code that it affects is nice. If the commit never makes it into master a TODO doesn't either. If the function it's in gets rewritten, the TODO goes away. etc.

I don't see why you'd hobble yourself by removing a method of tracking todos, in favor of one that's higher-overhead and more dangerous (much higher chance of getting out of date due to implicit coupling).

> If it's not worth of the issue tracker, it shouldn't be worth of a TODO either.

This is what I mean by throwing away work. If you have some insight about the code, your requirement that the insight be thrown away until you can "prioritize, track, and categorize it" makes no sense. Allowing a lighter-weight annotation that lives with the code that it describes allows much more flexibility: it's descriptive of the code and agnostic to its eventual fit into your tasking, as you can integrate it into formally tracked tasks or lump it in with related changes. Blanket bureaucratic rules for bureaucracy's sake is pointless, and I say that as someone who's a very strong believer in ticket tracking hygiene.

I agree with you - specifically because you said "accept that it's going to be wonky forever".

The advantage of TODO/XXX/etc. is that you can grep for it. I look for it before committing, vim will syntax-highlight it as an error, etc.

There's no point in grepping for every possible improvement someone might have wanted to do at some point in any part of the codebase. It's much more useful immediately. (I use XXX as a marker to myself for "finish doing this before sending out code for review," specifically because it does get highlighted as unusual in vim.)

If you've got something you want to do in the future, that's totally fine, just don't put it as a code comment. File it in a bugtracker, or if you don't have a bugtracker, put it in a todo file or something and check it in. That lets you at least slice up the work by area of the code (since there is likely no contributor who is equally well-equipped to fix a TODO in any arbitrary spot in the code and equally interested) and by priority and continued relevance. If you have the luxury/curse of doing this for a paying job with scheduled, paid developers, then proper project management will eventually cut the things you never plan to do (or you can use the backlog to decide to hire more developers). Whether or not you do, it's valuable to look at a proper issue tracker, or even a text file, and say "Hm, this thing is so full of unreached improvements that maybe we should flip out and improve it" vs. "You know, this is working fine, it's worth documenting for posterity if someone comes back to this code, but it's not worth specifically calling attention to."

If someone wants to document things about how and why the code was written a certain way - including possible other ways the code could be written, but isn't - a perfectly normal code comment will do the job.

Issues bugtrackers get lost, code stay. I prefer to see a TODO and have a glimpse of what was going on in the dev mind (or even my own mind, 6 months ago) rather than "hide this information for the sake of cleanliness." Just the same way, to a large extend, documentation should be in the code, not in a wiki.

Not for the sake of cleanliness - for the sake of storing the information in a useful format.

If you want the bugtracker or documentation to be checked into the same source repository, that seems entirely reasonable to me. I don't know good tools beyond text files for doing this for bugtracking (although I think Fossil does this, kind of, and I'm sad that Simple Defects never took off), though if your work is uncomplicated enough to go into code comments, it's definitely uncomplicated enough to go into a separate todo file, as I mentioned.

It's very straightforward to do this for documentation. Probably the right thing is to use your existing patch-contribution workflow for this, but make it lighter-weight for docs (reduced or nonexistent code review), but you can also hook up your docs to something like Ikiwiki if you prefer: being in a wiki and being in the source control repo aren't at odds with each other.

And for seeing what was in the dev's mind six months ago - use git log and git blame for that. Even TODOs get refactored away, or moved around enough that they no longer make sense. Good commit messages will show you the whole change that was being made, in context, and what the programmer was thinking when making that change.

Most devs I've been working with don't even bother with a full sentence in their commit log.

At this point, we're discussing between what "should be done" in a perfect world, and what's actually been done when you switch between a couple of project in a day, moving from "implementing feature Y" back to "putting down some random fire", back to "implementing feature X" within a day in an undermanned team. Sometime, a hack will get you back running in prod, and a "TODO" will be there next time you actually have time to address the underlying issue.

Oh yeah, a TODO is way better than nothing, no disagreement there.

If you have a code review step, "please move this comment from the code to the commit message / the bugtracker / whatever" seems like a reasonable comment. If you don't or you're bypassing it or nobody does good code reviews, sure, leave the TODO in. I am indeed talking about the ideal world and whether we think TODO comments are a good idea in the abstract.

> something you want to do in the future.. don't put it as a code comment. File it in a bugtracker...

Comment in situ has advantages:

- preserves context without duplicating it into an external system - promotes awareness of the issue when the surrounding code is changed in future, which can lead to serendipitous resolution. - particularly useful when the issue is one of internal quality (eg coupling, duplication, missing test case) that wouldn't ordinarily qualify as a bug or proposed functional enhancement.

In contrast, the bug tracker is a graveyard where such ideas go to die.

> TODO, XXX, or the like should not survive past the review stage

I'm afraid if you stick to this principle, you will never have any code ready for review. Using TODO is not an excuse for writing buggy code, but an indication of future improvements and optimizations.

It's a great rule if you want to get people to never write down whatever information would have been contained in their TODOs. Anywhere, probably. Best case it remains but just without the TODO label, so... congratulations? Or goes in an issue tracker with all the other junk-issues that no one ever looks at.

Having some way to designate that you're not happy with the code, but it works, is valuable for future refactoring. Another one I see a lot is some variation of "this is a hack." Grepping for "hack" in a codebase can be very entertaining. TODO is more to the point though.

And your kernel would likely never ship, at least not with many drivers anyways.

Don't forget Linux is largely a grassroots effort with heaps of reverse-engineered or otherwise improvised/ad-hoc hardware enablement going on. It wasn't until relatively recent history that we could even suspend/resume reliably!

Some form of tracking tool is the correct place to document the roadmap, in my opinion. The roadmap can be continuously monitored and updated. TODOs in code just end up as comments that exist for a decade because no one along the way wants to delete them, even if they have no relevance anymore.

Even though "mainline" has been structuring a tad over the past 5 years or so, Linux has no roadmap, no product management team scheduling features, no nothing. It is the epitome of bazaar development model done over mailing lists... and it's been working pretty well.

> Linux has no roadmap, no product management team scheduling features, no nothing.

I would bet large money that Linux has a great many of all three of those. They are just handled in a distributed manner by the various teams working on the different features.

Bazaar doesn't mean disorganized. It means there is no central planning authority. There are many individual planning authorities with their own agendas.

Whereas every issue tracker ever has no abandoned or ignored pile of ancient tickets?

Must be a nice place to work! Because I've never seen anything like that before.

Serious question as someone who drops XXX occasionally: There are all sort of places where you want to note "there's probably a better way to do this" or "maybe look at this edge case" or whatever. Not all of those are important enough to address in the next review/sprint/whatever...why isn't it better to leave them in and keep that tribal knowledge around rather that delete them and loose that insight?

Maybe a better question: is there a better way to collect those sorts of low priority tasks?

I think these sorts of notes belong somewhere external of the code itself; an issue ticketing system or whatnot. Because more often than not, I find those "TODO"s lose meaning over time. They often suggest a particular way to solve something, but by the time we might come back to fixing it, that solution is no longer the best way to do it.

A ticket can better express the problem, so that we can evaluate and triage how serious that problem is, and when the time comes to fix it often we'll come up with a better solution than the TODO would have expressed.

A FIXME is even more obvious: if something needs to be fixed, then let's track an issue/ticket for it, otherwise noone will ever know to fix it.

Interesting perspective. I don't per se disagree, but my gut feeling (that is, I have no idea if I'm right) is that the farther away from the source code those notes get the less likely they'll ever get looked at much less addressed. I think your view requires more discipline, which, of course, is what we should be striving for.

> Because more often than not, I find those "TODO"s lose meaning over time. They often suggest a particular way to solve something, but by the time we might come back to fixing it, that solution is no longer the best way to do it.

This seems dramatically more likely when tracked anywhere _but_ the code. As usual, implicit couplings are dangerous in engineering, and are far more likely to fall out of sync when they live far away from the code they're describing.

When the TODO proposal lives with the code, it's a lot easier for discrepancies between the proposal and the current logic to be caught and fixed, whether during implementation, review, or during later reading of the code. None of these possibilities for keeping the comment in sync with the logic arise organically when the proposed improvement is in a bugtracker somewhere, with no pointer from the logic to said tracker.

to a large extend, a TODO/XXX is meant for developers while a bugtracker ticket is targeting product management.

I very much agree that if you really want to get to the todos they should be tracked in your issue tracker and prioritized with all other work with the team. What's the alternative? Take a random afternoon to do a random Todo item instead of prioritized work?

Absolutely. That only works in an environment that treats its developers as responsible professionals, not ticket processors, though. If it's going to take a while, just create a ticket while you do it.

I prefer to minimize tribal knowledge of all forms. This does incentivize deletion over "it might be somewhere/in someone's mind", but it also incentivizes moving the knowledge out of the jungle and into something longer lived and searchable in a broader context. How much I prefer the minimization depends on the size/stage of the company, though... At early startups for instance, most tribal knowledge will take care of itself by being forgotten -- and no harm either since the subject matter it applied to is no longer relevant, that was x months ago and nearly everything has changed.

For larger companies, though, it's really nice to be able to pull up documentation (glorious if you can even use a public Google search instead of some intranet lookup or README) about something, instead of having to go on a safari to try and find someone who knows someone who might remember why X, find out they don't remember (or don't remember enough/don't have time for you until Later), and having to figure it out from scratch yourself like you hoped to avoid. Not having to do that for everything is such a nice experience that I'd like to encourage more of it where I can.

Coming to the specifics you highlighted, "there's probably a better way to do this", "maybe look at this edge case", to me those are topics for the code review. They can be rephrased as questions for the reviewer(s): "Do you think this could be done in a better way?", "Should we try and test this edge case or does it matter?" The answers are in the review, and possibly in follow up work items tracked by something.

Code reviews can contain a lot of useful knowledge. If your commits aren't trivially linked to a review, it's worthwhile to spend the extra 10 seconds and manually link them at the end for posterity. If you aren't doing reviews, or the reviews are crap, oh well, you asked and no one answered/cared and that's now visible. Don't leave the question in the code.

Thanks for taking the time for that detailed response. It seems to me the underlying theme here is "strive for more maturity in the development process". Good lesson.

Doesn't that just fall under the "don't let perfect be the enemy of good" ethos?

I suspect it falls under the "discourage truthful comments" umbrella... Beware of misguided incentives.

I amended my comment to hopefully be more clear about the point I intended to convey.

And as with all advice, it shouldn't be followed blindly.

I am hesitant to write this, because in general I agree, but let's say a product manager stops a feature short of completed in some sense, even though there are some aspects which would make the feature more robust, secure or optimized, the code gets released and one would need a tombstone as a visible nuisance and indicator for these aspects, wouldn't it?

I mean the best place to communicate important ideas and warnings about code, is the code itself isn't it?

If you've let a PM stop a feature short of something you as a dev think is rather important, you've already failed to some extent as a professional. There are ways out of such a mess, but it's better to avoid it to begin with, and if it really couldn't be helped, to have a paper trail if not only for yourself then for the benefit of others.

Coming to the project as a new hire, I'd find a "TODO[3 years ago]: maybe add a cache for X to speed things up on this flow" comment less illuminating than "We think this will probably start to fall over at some scale point because we're not using DB connections wisely (and maybe want a cache layer) but our PM didn't give us time [or 'we weren't able to stop the PM shipping before we had time'] to perf test and rework the flow that was patterned after all the other DB-conn-happy logic".

(Not that either comments are that useful -- guess why I'm reading this part of the code?)

But I'm mature enough to think, coming across such code without any of those two comments, that the latter scenario is more likely than "Argh stupid devs, stupid this-dev-in-particular who I can see with git-blame, probably never even thought of a cache! I don't even need to see if there was discussion in the review!" That sort of thought only comes with direct experience dealing with people who repeatedly show themselves as professional failures who should at least retire into management but even better should find a different career field...

Comments like "NOTICE: Don't optimize this loop or you'll introduce a timing attack!" are always welcome in my book. Though if whatever you're warning about can be enforced with a unit test, that's even better insurance against someone naively or even idiotically changing it.

> TODO[3 years ago]

The thing is, you might also be not reading that piece of code for the sake of performance optimization. In this case such TODO is a testimony of premature optimization being evil: like, the code has obviously been fine for at least three years without any smartypants optimization that the developer at that time envisioned to become necessary.

Though yeah, it could have equally been just a 3-year-old ticket in the issue tracker. However, you won't learn about it when casually exploring the code.

This may sound weird but I use TODO's to document things I expect to be wonky forever or at least for a very long time.

Things I actually intend to fix go in the tracker.

Yep. Tracker is for stuff that definitely will get planned in. TODO's are just little reminders for when returning to a piece of code some time in the future.

For actual immediate tasks, a TODO_123 with the active ticket number is more practical when stubbing some partially written code.

Ticket systems are great and I use them for pretty much everything I do, and places like github make it very easy to use them even for your small hobby projects.

However I still think it's valuable to add TODO and the likes to your code, especially when working on open source, since the issue tracker might not be around forever, you switch platforms, project gets forked, some part reused in another project. It also makes it much easier to get into a new code base, just like comments in general.

Even at work we do this even though using tickets for everything is mandatory. I like it. And in case we open source some stuff folks won't have access to our internal ticket system obviously, so having something more than "see #4642" in your code is good.

I can see a TODO from 1999 that could be fixed now. There couldn't have been a plan to fix it back then.

I don't run Linux myself, I'm not going to bother looking through some bug tracking system.

If someone had deleted the TODO then I think I would be less likely to contact the original author.

IMHO TODOS help code quality by informing the reader of the weaknesses in the code and considerations with which the code was developed.

As a result if it’s out of scope of the ticket then it’s better to have them left in the code then lower code quality by removing them.

> 1. Long-term improvements should be managed by a ticket tracking system. The code is not the correct place to manage that.

Your code will probably outlive your ticketing system.

It's also easier to grep for "TODO" than navigate any ticketing system that I've seen. TODO also tells you where the problem exists in code, which is not something that I often see on tickets. Additionally, the non-technical people that handle ticketing within most organizations are unlikely to recognize or prioritize code issues as actual issues. Some organizations might prevent devs from ticketing things themselves as well.

TODO see issue X is also a great way to link the two together.

Is the issue still worth fixing? Well the file was completely rewritten 1 year ago, the TODO removed, and no one requesting this now/pushing for it? Close it.

Have an issue but not sure if it's relevant so it stays open forever? I've seen issues outlive the code their for by decades because investigating the lots priority issue wasn't a priority, quick "see: function" references are similar, easily searchable terms which makes old issue review very fast to close. This also ensures the backlog is reviewed periodically

Let us know when you ship your perfect alternative to Linux.

That is an uncharitable interpretation of what I wrote, and I suspect you know that.

"Many over a decade old" fits pretty directly with what I wrote. TODOs are where good intentions go to die. They get added and rarely addressed or removed.

There are times where there is no review phase. It's a single employee, trying to get something done for their employer in a reasonable amount time, usually limited by a lack of colleagues (not enough engineers) or a rapid delivery timeline. The TODO gets committed, the code is shipped to production, and the TODO comment gets no further attention.

I agree and don't understand people who downvote you as a punishment for expressing your opinion.

A TODO item is missing significant business information: date, priority, severity, risk, impact, applicability etc and leaves all those assessments on developer's shoulders who shouldn't have to deal with it at all.

As a matter of fact, every time a developer encounters a TODO around the change he did, it suddenly becomes a burden. He needs to answer "should I be doing this?", "what's the business impact of adopting this?" etc. Even a simple code change can mean business impact in large projects and has regression risks. What if the aforementioned developer isn't at the right caliber for the task, but they don't know it and take it on?

Due to the missing information, it's very hard to analyze TODO data and come up with reasonable engineering decisions too. TL;DR: It makes everyone's job harder.

I only find TODO's suitable for personal projects where you don't want to go back and forth between IDE and the issue tracker.

Exactly, TODO comments are basically noise. Nobody goes through code explicitly looking for them, and by the next time someone needs to modify that code the TODO is very likely obsolete or just confusing because of how much the rest of the code and circumstances have changed.

In code reviews I always encourage replacing TODOs with a ticket or just removing them. I just can't think of any time when a TODO was actually useful.

You have almost converted me from using TODO. I typically place a "Note:" when there's code that is hacky but not obviously so, to provide context. I also make sure to provide a link if some kind to a relevant issue tracker.

But a TODO is something different. It's for prototype code, where I don't even know if the feature is going to stick around long enough for the hack to warrant fixing. It says "don't worry about just deleting this whole thing outright and starting fresh." It's graffiti to intentionally make the code uglier, so it's not confused for being part of some larger design. It says, "hey, so, I didn't actually expect this code to survive, but since you're here reading this, it clearly did, you're probably working on something related to it, and you might want to know a few things upfront because it's not going to go the way you think it should go."

"Note:" comments are perfectly fine. On the other hand, I've seen at least three distinct definitions for TODO in this HN thread:

- TODO should be a note about behavior.

- TODO should prescribe a small fix.

and yours: TODO should mean "don't worry about deleting this".

These different interpretations and potential confusion they would create make even a stronger argument against TODOs.

I'm afraid "don't worry about deleting this" was poorly phrased...but your point still stands

As a developer, seeing a TODO in there is a non-issue. I appreciate the context from the previous developer and I don't feel any sort of pathological urge to stop what I'm doing to fix that TODO (unless it's actually relevant to what I'm doing, in which case, I appreciate that it's there). The way you're phrasing things suggests that you don't trust developers to manage their workload. Is that the case?

Also, the notion that developers shouldn't be involved in "business information" is a non-starter to me. They should absolutely be involved, it's a big part of the job. If they wrote it as a TODO instead of adding something to the issue tracker, they probably thought that it was an issue that did not need to be raised to non-technical people or project managers. You know how managers talk about "managing up" all the time? Dev's do that too.

Reply on news.ycombinator.com