I'm sure in larger codebases it can get unwieldy with tons of TODOs from a lot of different people, but for personal projects I've always found them a good compromise.

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 really appreciate the feature of Jetbrains IDEs whereby the codebase is indexed for TODO comments.

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.

I think the main thing is sometimes you want the signal that there is work to be done in the code. In that case even if you track it on JIRA, GH issues etc. you'd still want to link it. And a reference is a bet on continuity so without a description in the comment as well you might lose the meaning someday.

There are readily available MCP servers for JIRA that let the AI fill out the tickets for you, right from inside Cursor.

Put it in your 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? 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.

How would that be discovered? If I inline a TODO comment calling out some tech-debt that I (we, our team) had to take on, then in the future when the next person touches that logic they will see that comment and might address it. If it's in a commit message it might as well be invisible.

Discovered by other devs? git blame.

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.

`git blame` is to answer the question "who did this, when and why?", where the who and when are automatic and the "why" is a responsibility of the committer (and reviewers).

A TODO is about something that is not there yet.

Instead of relying on people actively checking the git-blame for all of the code they're reading, why not just put a clearly obvious comment within the code itself?

I'm actually saying people can do both.

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.

I'd rather see a TODO in the source file than in the commit message because of discoverability issues with commit messages.

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.

Maybe this is what you're thinking of?

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.

No, I knew there's some trickery to avoid part of the noise in git, but it's not enough as I won't be looking at that log or blame everytime I read a file. Using a TODO comment still seems better to me.

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.

Do you not use an IDE? It's fairly trivial to run macros or add something to the command palette. Maybe some personal scripts you have been honing over the years?

Usually strong opinions like this come with a more developed workflow.

Well, I guess emacs might qualify as an IDE. Magit is great, but my point about discoverability in practice still stands. I won't be looking for logs from all files, and logs only show recent changes, so long foretold issues like scaling or reasoning won't be there either.

> Put it in your git commit message.

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

Most commit messages are bad, but commit messages are a terrible TODO list.

You're right they are a terrible TODO list, but old comments in the code are worse because you don't have as much context to work with.