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.
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.
> 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 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.
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.
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.
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."