My advice is to never place TODO comments in your code. It will become a graveyard for TODOs and annoy fellow programmers who come across it for years after it was written.
Instead
1. Quickly experiment with refactoring but stop if it feels wrong. We often underestimate how quickly we can improve the codebase. It's often better to try something quickly than waste time planning to do it.
2. Defer if it's a big refactor or you're on a very tight deadline. Write a reminder in your physical notebook so you don't prematurely pollute your board. If it feels high priority after that and you still haven't had time to do it, then make a chore ticket for it.
Placing TODO and ASAPs in code helps ensure you don't leave any loose ends, and if you call another developer onto your feature branch allows them to get a feel for how you're getting on and how complete the code is.
Using a physical notebook distances the workload from the code and hides the fact something is incomplete from others.
A TODO graveyard can be prevented when you review the code - a developer who thinks a feature branch littered with TODO annotations is complete code is either dreaming up future use cases or failing to complete the work assigned.
> Using a physical notebook distances the workload from the code and hides the fact something is incomplete from others.
Exactly. In fact, I use both (except the notebook is an org-mode file, not a dead-tree book). TODOs / FIXMEs in code are for things very context-dependent and connected to code, for which it's important to see them in surrounding context. In more abstract cases, I just log a task in my notebook, to be done later.
Examples of both - code:
//TODO resourcify
(i.e. move to external string resources database later)
vs. notebook:
** TODO Refactor the refactor of the SomeClass class.
--
Also, often TODO / FIXME comments serve for me as anchors in some larger refactoring processes. I tend to label them specifically for easy grepping (e.g. with unique Unicode chars like ). The point is, refactoring process may take few days, during which I also may need to do some other tasks, so whenever there's a piece of code that needs to be redone but not right now, I tag it for later; I can then use grep/IDE search to check if I didn't miss anything.
I think you're both right. It's okay to have them locally or on feature branches for communication and note taking purposes. But they should never live for any prolonged time in your production code.
TODOs are ok when you're keeping track of what you were doing the previous day and what have you but for anything long term they are awful.
If you want other developers to see these TODOs in mainline, then they shouldn't exist and instead be in your teams project tracker.
Would you put every task as a TODO in code? No of course not. Its not easy to manage by non-coders, low visibility to anyone not in the file in question, no priority or organizational quality, no way to prune or plan these TODOs, etc etc.
If you would wouldn't put every task in a TODO, why put any task?
If you invest heavily in TODOs you just end up with things that should tickets and aren't or vague desires that would never end up as tickets because they're not well thought out anyway.
The argument isn't that TODOs should replace tickets. There's a place for both.
Often, by the time you officialize a TODO into the ticket pipeline, you could've just fixed it yourself. But the reason you dropped a TODO was because you were already busy with something else more important.
TODOs just sit at a local, unofficial scope in the code. I'm not sure what kind of things you put into TODOs, but if you were to generate a ticket from each TODO in the code I work on, you'd have generated a bunch of low value ticket garbage.
The problem with a rule like "no TODOs allowed in the code" is that TODOs are issues that aren't usually worthy of a ticket, or at least not the time to turn it into one at that exact moment. You'd just be blind to more issues. Not a reason to pat yourself on the back for 'clean code'.
This is classic Black and White engineering advice, which shuns pragmatism because some idiot could come along and make a mess of the codebase. If someone is capable of displaying such bad judgement for such a trivial matter then they shouldn't be working on the code in the first place.
Take the Tensorflow codebase (and Google and Microsoft code, and linux in general). There are currently ~1,028 TODO's in Tensorflow, most of which refer to a particular engineer in the form TODO(<name>):<comment>. This is pragmatism and good judgement in action.
Software engineering is all kinds of shades of grey, competing considerations, trade-offs and balances. It's what makes it interesting.
I disagree. Working on a large software project with many programmers, it is very useful to see what other programmers intend (or just hope) to change, even if it is just to get more of a glimpse in to the intention of the dev.
I find the usefulness/annoying ratio to be very high.
The problem is not in how these issues are recorded, but whether they will be acted upon. It is all very well to say just fix them immediately, but we all know that will sometimes (often?) lead to issues simply not being noted. Putting the issues elsewhere is no guarantee that they will be acted upon, and any rule you make to try to get them addressed, such as fix before check-in, will again lead to them not being recorded in the first place. In fact, if you find TODOs in code to be an irritant, perhaps that is the best place for them!
The code is where TODO's should live. Anything else can be separated from it. It'll help people understand areas where technical debt was intentionally incurred and expose them to the tradeoffs involved at a high-level.
Also, not all tech debt is solved by refactoring.
TODO comments aren't suitable for tracking all technical debt, but they're good for targeted instances.
This is exactly my stance on the matter. Don't litter the code with unnecessary comments that will never get acted upon. Instead, make a story in your bug tracker and act upon it.
Not only that, but bugs come and go. People add a bunch of tech debt issues into the system, then a bunch of feature requests, possible bugs, and whatnot gets added. Then some big milestone or release comes up and everyone filters through the list, deciding what to fix and what not to. And then anything that doesn't need to get fixed "RIGHT GODDAMN NOW" often ends up on the ash heap of history, never to be seen again. And then years later someone looks at the code or runs into a bug and remembers "oh yeah..., hey, we should fix this eventually".
If you want to fix/change something eventually at some indeterminate time in the future then comment TODOs are a good place for that sort of issue to live.
Instead
1. Quickly experiment with refactoring but stop if it feels wrong. We often underestimate how quickly we can improve the codebase. It's often better to try something quickly than waste time planning to do it.
2. Defer if it's a big refactor or you're on a very tight deadline. Write a reminder in your physical notebook so you don't prematurely pollute your board. If it feels high priority after that and you still haven't had time to do it, then make a chore ticket for it.