It's not at all meant to be to be like an item in a TODO list. Code would be a terrible place to keep that.
The more essential the change/fix, the more hashes. Made it really easy to do a global search for them, and you could easily filter the results to only show the most important ones by searching for longer strings of hashes.
Twenty years later and I’m still doing that in my personal projects.
Using code comments really seems like the wrong place to prioritize changes. Even on personal projects.
I personally wanted to contribute to a few projects but it was difficult to track what is currently being worked on or what needs to be done. When an opensource developer only works 8 hours a week on a project you don't want to waste their limited time by having a dozen people ask them what needs to be done and then not doing anything (because a feature might not be relevant to you but you couldn't have known that because it wasn't written down).
A nice cli interface for creating tickets in GitHub/Jira/etc. would help with that. I wonder, would it be nice to have a pre-commit hook that scans for TODO comments, removes them, and drafts tickets? Then both flows would work well.
I linked https://github.com/dspinellis/git-issue in another comment but it gives a sense of the command line experience. I've also at times hacked up various scripts to create or modify items in github/jira/our internal POS, it can make things more likely to hit the tracker than to be met with a shrug. (It's so odd how sensitive programmers can be to even minor blocks in flow like a few seconds waiting for a webpage, or avoiding refactoring a method / class because in Java a new method might best belong to a new class which to do things 'proper' often entails a new file and then another new file for unit tests, adding them to version control, and all that takes like 30 seconds even with IDE support and is annoying.) I've at times thought about a small vim command that would call one of those scripts to create a new issue pre-templated with the file and location I was on, create, then insert the work item id, but never got around to it. As a pre-commit hook something to look for TODOs explicitly might be interesting, though I generally dislike hooks.
It works only for gitlab and assumes that the remote is named origin.
This will create an issue with the title text being everything after TODO. It does not support multiline and only looks at the newly added lines, but does not remove from the commit or alters them.
It's a poor place for long-term tracking, but it's a great place for recording notes while minimizing context-switching cost while coding.
I also use ###. It is just a different style.
These should not reach the master codebase and should thus be fixed before you merge your code into it.
Obviously if “next release” is a deploy from master in 2 weeks then it isn’t.
The "accumulation of issues" is there regardless. Leaving TODO's isn't cutting corners or accumulating technical debt. It's simply something that is still to do. Any project will have an issue management system with outstanding issues, but a note in the code is worth more than a thousand words in an issue. "TODO: here is where the validation of parameters must be done, see issue #123". or "TODO: enable right-to-left in these two textboxes when right-to-left text input is added, see issue #234".
There is no value in keeping a main branch "clean" from TODO comments because it's somehow more hygienic. The code needs to be runnable at all times, even with incomplete features. Reaching zero TODO's before a product ships is a matter of grepping for the strings.
> “this is a thing which is okay during development but absolutely must be changed/fixed before shipping this product”.
There is no valid reason to submit effectively defective code to the main branch. There is a major difference between incomplete functionality, which obviously is what the codebase contains during development, and defective or sub-standard implementation.
As an example (and from one of your examples), leaving validation of inputs "for later" is a sure way of shipping code that does not validate inputs and, again, there is no reason not to properly implement this from the get-go.
This sort of issues only accumulate if you let them by cutting corners.
Real-life example: I saw things like "TODO: Check for null pointers" in code. This should be rejected outright during code review. If you should check for null pointers, then do check for null pointers.
But yes I agree it's a poor example if it's possible to do right away it must be done right away. But I think you get my point. RTL-input may be the better example: it's a nice-to-have for some people, probably not part of an MVP but still a likely part of what some stakeholder calls critical functionality if you support RTL input locales.
My point is that while you may be able to categorize some things as "critical" or "important" (i.e. things one can argue should not reach the mainline even during development) there will always be a gray areas where you can't complete the development, but should still have a functioning app in some sense.
If you do stakeholder demonstration from an integrated “develop” branch and ship from master, you can have a policy of “no TODOs in master” meaning you won’t ship the TODOs. I’m not saying one must have TODOs ever in the branch-that-will-be-released but that they can be very useful and almost unavoidable to have in some integrated branch, because you may need to show a product without it necessarily being ready. Exactly what quality gates you ship with is a preference, for example specific comment tags (PERF, FIXME, TODO, ...). These are just words. In my codebase TODO means "this works but isn't optimal, so should be revisited IF the code ever has a reason for change". In other codebases it might mean "This is utterly broken and can't be shipped". Whether shipping is acceptable of course depends on which of those interpretations one uses (And using both would be a process error).
I assign the same meaning to TODO or FIXME markers but a lot of people see this is as a measure of poor quality so instead I write regular comments of the form "this could be made better by doing X and Y".
grep -rn TODO *
"Intellj supports it" is a pretty meaningless argument anyway.
That's fine, they don't need to be tracked. There are other systems for issues that need tracking.
I would like to have a tag for "here's something that works, but could be improved" though!
It seems nice to have tags for places to jump where the improvements are obvious, rather than hoping to just remember/spot them later.
Seemed weird to make up a codeword but I wasn't aware of any standard convention, and visually highlighting high impact issues (w/ the bonus of greppability) seemed like a sane approach in rapid development environments.
For personal projects I've used https://github.com/dspinellis/git-issue a few times for a local command line issue tracker, it's not bad. I've got a longstanding mental TODO to try out Fossil one of these days though with all that and more integrated...
HOWEVER: For a mature project, TODOs should be found and reviewed during the pull request. Either they should be fixed prior to merge, or a ticket should be filed. (With a link placed in the TODO comment.)
In the rare case that a TODO remains without a ticket, it really should be something obscure that really doesn't need to be fixed. For example, TODOs are great for micro-optimizations or suggestions for long-term refactoring.
Only so many times can you scroll past a nagging ide hint before you say "FINE, I guess I'll do it now!"
Lowering the barrier to see such comments increases the chances of people actually handling them. Having a highlighted TODO in the code makes it much more visible even if you don't use grep.
Personally I hate TODOs and only see them as temporary things to act as placeholders for the correct code. At some point, I will go through all todos and clear them.
A lot of people use them for things that "could" be done.
The reason I use not just a comment is what others here already said, it gets highlighted by the IDE, and I have too many other "gray" comments that would not get read unless someone is looking at those sections specifically, so another regular comment would be easily overlooked. The suggestion for external tools or files is even worse: Pretty much nobody will check them when it's time for refactoring. It has to be inline. Sure, it can't become too much, but one such "triggerable TODO" comment for just a few modules is fine.
When I write the code I can often already see options to make it more scalable or generalizable, but as it is currently being use the additional cost is not worth it, and if there never is future expansion the code actually is fine as it is. When I already know what needs to be done because my brain is fully 'inside' this code it would be a waste to throw that knowledge away, and regain all the contextual knowledge and ideas with a lot of work a year later. Those are the cases when I add such comments. They are not necessarily "TODO" level at that point, I use that tag only when additional conditions are met and I'm sure I want to avoid missing the comment.
Occasionally, when I have some time over, I scan through my TODOs, there are about 2/1000 LoC. Most of them I leave alone because the condition for their realization has not been met yet, but sometimes I find one of them is worth doing at that point. If it was a general comment I would have no chance to find them that easily. If they were in an external tool or file they would deviate from the actual code more and more, since we do quite a bit of refactoring due to growth and changing needs. But if there's a highlighted TODO in a module you are refactoring it's impossible to miss, so it is easy to update or remove those if they become invalid, even more so than regular "gray" comments.