First and foremost, this post is more of a personal guideline to myself in order to stop, what I consider to be, a bad habit of mine.
Adding in-code TODOs is something I'm trying to move away from. While it does create an immediately contextualized task list when placed in the surrounding code, the list can only be observed when you open those specific files. Essentially, there's a growing list of TODOs with no impetus to get them done until they are rediscovered by opening whichever file they are in.
Additionally, they pose the problem of being difficult to track which makes it hard to chart your progress. They basically sit there, doing nothing and tracking nothing.
My personal goal is to begin migrating all of this TODO tracking into some other format. Options like Todoist projects, Google Keep notes, or desktop options like FromScratch create a more centralized alternative for keeping track of what needs to be done and helping to keep a focused approach. Personally, I'm using GitHub Project boards with Markdown checkbox lists - these have a nice feature of showing a progress bar as you check off items.
Now far be it from me to say that all in-code TODOs should be abandoned - there are some instances where it makes sense. For example, I feel like when I'm jumping around in several files, jotting down TODOs as I go, it creates a sense in my head that I'm laying groundwork for the immediate future. Perhaps even using them as "bookmarks" for what I'll jump right into the next day.
This is all just my opinion and if other people have differing opinions / better ways of handling this particular stumbling block of mine, I'm all ears.
You say that "the list can only be observed when you open those specific files". Any good editor or IDE will have a tool to negate this problem. Atom has a package called todo-show that shows the type (it supports more than TODO, but also things like FIXME, IDEA, NOTE, REVIEW, BUG, QUESTION, and more), the text after the tag, and what file it is. Eclipse also supports "task tags" which all you to specify a tag (like TODO or even custom tags) and assign the tag a priority and find and filter all of them through open projects. Even Visual Studio supports a task list that's very much like Eclipse's. I don't regularly use emacs or vi (I prefer a more integrated environment that's harder, but not impossible, to get with those editors), but it looks like there are solutions for these editors to do similar things.
Once you get past the problem of finding all TODO-like statements in a project, the value of putting them in the source code significantly increases. They are there for any developer to pick up. At work, we track work to pay off technical debt in JIRA. On personal projects, I put in a GitHub issue for things that I know I need to get back and fix. But I also put in TODOs or similar in the code so when I decide to go back and fix the problems, I have a much better understanding of what is necessary. Especially in a team environment, getting the fact that there exists undone work or technical debt is important, having the information to go forward and do the work or pay down the tech debt belongs in the code.
Good to know about the
todo-show- I'm an Atom user and I think I'll play around with it.I'm very much a proponent of self-documenting code but perhaps extending it too sharply into excluding TODOs isn't the best manifestation of that philosophy. The idea of having the TODOs framed by the context of the surrounding code is very appealing but I also like the ability to view things as they relate to the broader project or how TODOs relate to various sub-tasks. Essentially, I'm trying to wrangle out a good balance for myself for where to use in-code TODOs and external trackers without tipping to heavily in favor on relying on one or the other.
It's a balancing act, for sure.
I've found that external tracking tools (JIRA, issues in GitHub) are great for planning and tracking. At work, great for showing status to management or letting non-developers understand how work is progressing. In personal projects, figuring out what I want to sit down and do in a limited amount of time.
Lots of different people have different variations of TODO. Personally, I dislike things like FIXME or BUG in my code. If it's a bug, it should be fixed. If, for some reason, it can't be fixed, the issue should be outside the code in an issue tracker. At that point, the TODO becomes a reference to an issue tracker. Other people have other comments - HACK, XXX, TODO, NOTE.
Personally, I think it comes down to audience. If it's at the level of detail that a non-developer needs to know about, put it in a ticket so your non-developers (users, managers, product owners, whoever) can find it. But TODOs can make it extremely easy to find parts of the code that need work and put in more detail.
Like anything in the code, though, it does need good tools to manage. Leaving TODOs without a way of tracking them or the discipline to keep them up-to-date is likely to be harmful.
I have this alias in my git config for this exact job
Short, sweet, and it will even tell you which line and which file it is part of. Then you can add a pre-commit git hook and it will remind you of your TODO's every time you commit. OR, you can make it reject your commit if it contains a TODO line in it pretty easily too.
That's actually really cool. One of the concerns I have with the in-code TODOs is that they will be lost and buried if they aren't kept front and center.
Perhaps it's obnoxious to point this out, but this is what grep is for. Unix is there, use it! If you want, put it in a hook so you see it when you interact with source control.
The benefit is that you create the mark when you write the code. It's valuable whenever you are writing code without time to do everything perfectly. Opening an external loses the immediacy.
Someone's only going to grep if they know to do so. I think the spirit of the article is to suggest a better task management system than in-code to-do comments.
I have fallen prey to this team myself. Now I use Jira tickets or GitHub issues exclusively.
"This reminds me of a new feature we could add" does not belong in your code, and "I have a funny feeling about doing it this way on line 27" does not belong in a ticketing system. It belongs on line 27.
Both inline TODO and FIXME comments and external tools have a place.
If you hack something under a deadline and don't comment it as a hack out of some notion that inline todo comments are bad, I'm not going to thank you if I'm the one reading the code later on. Of course you can always add "cleanup the hacks in the foo module" to your ticketing system as well.
My teams use checkstyle at build time and will fail the build on checkstyle errors. I added a custom checkstyle rule that will fail if it sees a TODO comment that doesn't reference an issue tracker issue.
As long as the team's small and bought into it, I've found it results in just the right amount of friction such that if you're just pushing something small off until later, the pain of opening an issue and writing out what needs to be done is equal or greater than just doing the TODO. But if it's sufficiently large, then it gets tracked in the issue tracker.
Again, there are plenty of ways to game this kind of system so the team needs to be bought in. The checkstyle rule just serves as a reminder.
Other point to consider is that a contextual TODO may change in a code base. Issues or Jira tickets with links to code surface the information better without requiring code commits to clean up.
Jetbrain IDE's show you a list of TODO's throughout your project. You can double click them to jump directly to the file and line it's located on.
We have a lot of tools to manage different projects instead of still using TODO files. I agree with you, we must abandon TODOs.
Btw I use Redmine for my company's developments and Taiga.io for my personal projects.