I'm with you here.

> 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 like the XXX idiom

     //XXX this is bad
     //XXXX this is more bad
     //XXXXX this is EXTREMELY bad

Allows for easy grepability and a rough, at a glance evaluation of the seriousness of the hack/debt

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