Ideally tech debt or code-smell encountered like this would be captured/tracked/described better but often-times this means context switching or engaging in some kind of high-friction activity (like filling out a JIRA ticket) and that just discourages tracking it at all. At least inline TODOs are captured somewhere. And they can be for doing.
For me it's saying "yeah I know it could be better but I'm not going to break my train of thought over this and context switch. It's not so critical as to break functionality, this would just be nicer."
I really do appreciate TODO hilighting in editors for the odd occasion where I get back to something on a whim and feel like doing a quick fix then. (It's probably not realistically that common though and most will sit there indefinitely)
I often find myself with some time on a plane and cracking open my laptop to dig through to the TODOs that are shown is really cathartic.
Most commits people make are rather bad. Instead of taking us back to the stone age with TODOs, why not encourage better tool usage? Many don't commit often enough and instead tangle together unrelated changes. The cherry on top is when the commit message is just "updating somefile.py" or something similarly unhelpful.
Discovered by the rest of your org? I don't see how a TODO in the code is more visible than a git commit message. In fact, at least it's possible that non-devs may still be able to see the git commit messages in a feed or have read access to repos.
What I take issue with is low quality writing. TODOs are a low quality comment. Commit messages that only tell "what" and not "why" are also low quality. Generally just not having a clean history to look at is bad project management.
A TODO is about something that is not there yet.
Maybe that can be fixed? If I need to git blame the right line, and while ignoring miscellaneous commits like formatting changes, renames, and additional comment additions, then I'm probably not going to find the commit message. Also, if you do all of that just to find a vague commit message, then why bother digging next time?
Best tech-debt tracking I've seen is in the form of TODOs with mandatory links to the issue tracker (thanks to a silly regex pre-commit/pre-submit check) coupled with a team culture of adding such TODOs, as just adding the regex check will just cause lazy and sloppy engineers to not add a TODO at all, especially when facing pressure from other teams.
git log -pM --follow --stat -- path/to/your/file
This will get you all the changes a file has gone through. You can also add --ignore-all-space if that's a problem.
A TODO surfaces details where it wouldn't even occur to me that there's something interesting hidden in the log. Trying to find them feels like smashing the action button everywhere to get a random secret in a game, like secret doors in rtcw or finding stuff with the shovel in zelda.
Usually strong opinions like this come with a more developed workflow.
Yes, that's fine. Developers can also put TODOs in their git commit message.
> Most commits people make are rather bad. Instead of taking us back to the stone age with TODOs, why not encourage better tool usage?
I have a tool which fails if it finds a TODO in a comment without a Jira link on the same line. Since it fails if it finds such things, it's great for CI/CD piplines to block PRs until all of the oddball ends have been tied up and made visible to the product team.
Alas, if we could get the product team to prioritize those TODOs then they can start to be removed from the codebase...