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