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.

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.

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

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.

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.