Plotting the source code “TODO” history of the most popular open source projects
schleiss.io
schleiss.io
We'll get to it. Someday.
There used to be an ASCII art version occasionally slapped on Usenet posts: "here's a round tuit, you can go ahead."
You can output to markdown or to GitHub issues with a token.
I used to operate a service that did this for you.
The kind of TODO you're talking about is splitting a ticket into parts so you can hit an artificial deadline (ie, it's no longer 'done done', it's just 'done'). If the artificial deadline is your boss, then we're in a bad place. If it's another team needing a feature, that's pipelining and that's often okay.
For the TODOs that make it to PR without human error, I write most of them for the next person who adds functionality to an area, to either encourage them to do so or at least not make things worse. But sometimes it's for the person who hits the Rule of 3.
Those TODO's should be addressed in six months, not two weeks, and having someone call me on them in a PR is not particularly helpful. No, I'm not going to quadruple the scope of this story because you don't like the word TODO.
At least this is needed for any meaningful comparison between project (or even in projects themselves, as some double in SLOC count over a few months)
I don't know wether to suspect that's because it has
a) an overly parliamentary development process that just creates lots of bookkeeping side affects
b) a very aspirational development community that is busy writing tons of "try to take over the world" goals to improve in various and sundry ways
c) indicates a lot of short sighted/highly focused language evolutions that leave a long trail of todos because that kind of "we have no big picture" creates a lot of corner/edge cases that need "todo" signs to document them
d) something else?
Someone at PostgreSQL and Django is actually reading and fixing the TODOs.
We had a couple of projects that had unit tests neglected so we enforced that you had to round up to the next closest 1% on the package.json for your merge to be approved (as well as adding some unit tests)
In 3-4 weeks, code coverage slowly went from 20% to 73%.
I believe that one of the cognitive dissonances with people who think a lot of code is good news is that they become overwhelmed by how much they would actually write if they stuck to their convictions and so they start using TODOs to make themselves feel better about doing the wrong thing.
Projects that grow slower I suspect have fewer TODOs.
One related tip for devs: I've started adding "You are here" as a placemark for where I'm working in the code. So for example, on friday, if I want to pick up quickly next monday, I add "//TODO: YOU ARE HERE Finish doing foo". Then on monday, I search for "You are here" and pick up where I left off easier. Saves me a few cycles, though if I'm honest, I have quite a few of those hanging out too.
I forgot how I went from "Water in the well" to "ink the well", though. It's been a while since I started doing it, and I wrote a blog-post[1] with some scripts and helpers that I still use.
[0] https://www.fastcompany.com/3021905/hemingways-secret-to-mai... [1] https://berk.es/2012/05/30/leave-some-ink-in-the-well/
This turns out to be very hard advice for developers to follow. I don't say that as a complaint about Hemingway, but as a complaint about developer neuroses.
I have tried many, many times to convince people to associate their 'sense of completion' not with the act of getting their changes into master but the act of committing their changes (or pushing it to a branch, if you are PR-driven). It works less than half the time, and almost always with the more junior people...
So many incidents of someone staying late to finish something, pushing it, then coming in late the next day (because they stayed late) to a bunch of upset coworkers who had to clean up the mess they made.
Completionism will be the death of us all.
I'm not sure if I understand you entirely correct, but it seems the "you have to commit" is a large part of the problem.
You don't.
Your harddrive is not going to crash between tonight and tomorrow. And if it may, and this is crucial, git is not a backup system, so get a proper backup system in place.
Commit when you have a coherent piece of work done. Or maybe commit a "WIP: working on foo, halted for emergency hotfix X" if stashing is out of the question.
Part of my "INK" workflow is not committing to RCS. Leave the dirty state as another mental nudge what you were working on; and add your current memory-state as annotations in the code behind an INK.
I've mentored a junior and he was the opposite, never committed untill he was finished, sometimes work of multiple weeks, then he commited it with "finished the FooBar". We agreed he would try to commit at least daily. So then he made one commit a day. "17:00 going home. commit" in the logs. Every day. Needless to say, we did not keep him for long.
No, that's the problem.
Commit when you are available to deal with the consequences of commit. Having a coherent piece of work reduces, but does not eliminate the chance for problems. If you leave before the code builds, you've created problems for someone else to fix. If you haven't budgeted time for the rollback to go wrong on the first try, you're creating problems for other people.
This is why reliability and responsiveness of CI/CD systems matter much more than most people allow. On a good project, pushing things after 4 is probably a bad idea. On less well run systems, anything after 3 might be risky. On a bad one, 2:30 might be pushing things. So depending on meetings and lunch time there may be very small intervals where you can push things, and when the clock is ticking we begin to rationalize, which just makes the likelihood of failure increase.
I'm curious to your workflow now. How can it be someone else's problem if you do not commit (and/or don't push) your work? Is everyone working only on master/main/develop branch? Do you work in a shared drive? Is your entire team working off a dropbox or network drive (I've seen this, I needed eyebleech)?
TODOs offer valuable insight but they may not warrant turning into issues or stories. Removing valuable information because it's cluttering seems like a shame. Better if you can filter it in such a way that it doesn't clutter
This information is often completely lost in issues that noone will ever look at again.
I also like to do TODO sweeps, but with a bias towards rewriting the into documentation or leaving them in if the are actionable.
NOTE: Attempting to re-synchronize here would cause an infinite loop because...
Notes are great but the context is to make a note about something that can be improved in the future (something actionable), hence it being a TODO.
"This information is often completely lost in issues" - of course, because an "issue" is "a vital or unsettled matter" and are not meant to be revisited once resolved. Writing design decisions or thought processes in issues seems equally weird to using TODOs to document that. They're kept around because it costs nothing and you might want to refer back to it for details on some past problem, but I've never heard of that being considered documentation.
$ rg FIXME compiler | wc -l
1036
$ rg FIXME | wc -l
18656I think it makes sense to get rid of inline TODOs.
On new unshipped projects I've gone down the road many many times where it starts with a TODO comment above a chunk of code and then it turns into a few lines of context or a summary of my thoughts. Then comes linking to references, recapping my thought process on the "why", potentially writing a couple of versions of the code and keeping them commented out, or even having a chat with a friend over IRC and copy / pasting the conversation next to the code.
Now you open a file and suddenly it's your code mixed with a massive brain dump of notes, research and a ton of other things that have no business being in your code base and of course your intent is to remove all of that stuff once you get the well thought out implementation but eventually all of this stuff builds up. Then it happens across multiple files and eventually it becomes really hard to figure out what you need to do.
Putting all of that stuff into a kanban board has been a huge win for me. Now I just drop all of that contextual info into a "research" list and I pick things off that list when I'm ready to really do them.
A made a video about this process a while back at https://youtu.be/HHOkcCqsipE?t=77. It shows an example of the before and the after.
Just because you (and I) see correlation with our expected biases shouldn't be construed as proof: merely interesting chart wiggles.
I think the shape (monotonic increase or sawtooth) can be used to see how a project handles either missing features of technical debt.
Not only will they not do that later, but at some point they will compare their productivity to someone who ended up having to 'do that later' for them, causing their other work to suffer.
https://blog.zecops.com/research/from-a-comment-to-a-cve-con...
Sometimes the vulnerabilities are just handed to you on a dark-themed platter and I don't look them in the mouth.
TODO: high: don't use bogosort
Would only be useful if it became a defacto standard though
At least it works in PyCharm, so most likely it works in all IntelliJ based IDEs.
Wikipedia's list of versions suggests that this was probably related to version 3 happening in July 2019.
They never get prioritised and very rarely does anyone get to do them.
So what’s the point? It feels like a todo is really only there to serve as an excuse for suboptimal solutions.
I'm working on a personal project right now and in order to see how things look, if they work etc, I've got a bunch of vanilla js frontend code and //TODO in a few places to call an API and get actual data. It works great for now as I've hardcoded everything, got it looking broadly like the finished product, and it means that I just have to do the API calls (and programme the API too, of course).
I use them a lot.
Not only are you rarely gonna have the time to fix the TODO, but weeks, months, years later when you run into a TODO in your code, you have no idea what the actual requirements were, why it was not implemented, why it hasn't hurt anyone and whether anyone is actually needing it. Thus the TODO comment will remain forever, as you can't figure out what to do about it, without investing a lot of time and energy on requirement engineering.
Personally, I've started to block PRs with TODO comments that aren't directly mentioning the future implementation story/bug. As such, even if the TODO is forgotten in some way, you at least will find a reference point to what should have been done here.
This depends entirely on the team, company and/or work, though. It certainly is not a given.
> TODO in your code, you have no idea what the actual requirements were, why it was not implemented, why it hasn't hurt anyone and whether anyone is actually needing it
This depends on the task you are TODO-ing. Sure, if it is a "TODO: seems broken, fix." or "TODO: make sure that users don't see this", you are putting not just the wrong things in TODOs you are not giving them enough context. Compare that with a "TODO: this duplicates the routine in FooBars#bar_bar, but we cannot move this to a generic helper until the BarBar can handle both ActiveUsers and PendingUsers. Once that polymorphism is implemented, this can be DRYd up", which gives context, predicaments, and communicates that the author knows it is suboptimal, and explains how the author would've fixed it.
I much rather have someone finalize their implementation and create follow up stories/tasks to indicate what needs to be done next, than having hints of what should've/could've been done and nobody ever going back and cleaning those up.
That's not the only way to use a TODO, but even if it was, it's still valuable to mark suboptimal code.
Imagine you're investigating a performance bug and see a comment in related code which says "TODO: use a faster sorting method", that's probably going to be helpful.
It would be a really bad practice to merge procedures and policy with technical artifacts. TODOs embedded in the code are technical artifacts, they say what should change, they really shouldn't say how and when.
> They never get prioritised and very rarely does anyone get to do them
Well, you are faulting the tool for your development practices. If your team doesn't look at TODOs, you indeed should avoid them. But that doesn't mean anything for other people.
At my workplace embedded TODOs would be bad too. At personal projects I find them quite useful with a similar life-cycle to warnings: you keep them there while the feature is being developed, but they must be gone by the time it's complete. Other people have different practices, and may successfully use them in different ways.
1) Need to do a hotfix on some bug. Fastest fix is to just turn off something.
2) I turn it off (maybe commenting out the line) then add a TODO above it with the ticket number that corresponds to the ticket for turning it back on once the issue has been investigated.
3) Once I start working on the ticket to turn the thing back on, having the todos makes it easy to know exactly what to do (context isn't lost) and I don't end up missing some things because I can just search all of the TODOs.
4) If a TODO is missed, we have a script that will re-open any ticket for which a TODO ticket number is still in the codebase. i.e, let's say we have "TODO: xy-123 ..." If i close xy-123 without deleting that line, the script will re-open the ticket and comment saying that there is a remaining todo
PHP's 3 years 2011-2014 are much shorter than 2 years 2014-2016. NodeJS's years 2017-2020 that were ~50% longer than 2013-2017.
[edit: reasonable answers below, thanks!]
TODO FIXME XXX
BUG NOTE CHECK DEPRECATED HACK TBD FIX TEMP REFACTOR REVIEW HACK Todo
git rebase -i --exec 'ack TODO | wc -l >> log' HEAD~20
git log --format=format:"%at %H" | sort -nr
You can then use e.g.
date -I --date='@1620720025'
The next step would be to loop over the list, checkout each revision, grep and wc the TODOs, and collect into date buckets. Anyone? :)
This prints the years - you can the group and plot them as you wish (it should be fairly easy, but I wrestled enough with git). It's a non-rigorous script (eg. it assumes nobody's email/name includes an `YYYY-MM-DD`-like string, and that filenames don't include the colon character):
grep -P '\bTODO\b' -n -R -- * | awk -F: '{ system("git blame "$1" -L "$2","$2) }' | perl -lne 'print /(\d{4})-\d\d-\d\d/'
- grep prints filenames and lines
- awk captures the filename and line, and executes a git blame on it
- perl matches the year and prints it
In the Perl matching expression, month and day are not strictly necessary, but disambiguate potential 4-digit numbers in the email/name.
I'm very underwhelmed by the lack of customization of the `git blame` command - `--porcelain` is also uncustomizable, which makes things even uglier.
Note that `git blame` also mishandles some edges (printing "fatal: file [...] has only 1 line").
git blame --line-porcelain "$1" -L "$2,"$2" |
perl -MPOSIX=strftime -lne '/^author-time (\d+)/ and print strftime("%Y", localtime($1))'
All that said, that pipeline is quite slow on something like linux.git, as it runs a series of blames which will walk over the same history many times. I think:
git log -STODO --format=%ad --date=short
It increases the complexity, due to time conversion. One can certainly solve the general problem by throwing enough awk/perl/sed at it, but an option to customize the blame output would make it significantly more ergonomic (and the oneliner much simpler).
git --no-pager grep -I --full-name --line-number 'TODO' |\
sed 's/\(^[^:]*\):\([0-9]\+\):.*/\1\n\2/' |\
xargs -d '\n' -n2 sh -c 'git --no-pager blame "$0" -L $1,$1'
What it does:
1) git-grep for files that are checked in, not "binary" that contain the string 'TODO'
2) sed away the actual line contents (git-grep doesn't seem able to only output file:line-nr)
3) use xargs and sh to call git blame on that file:line-nr
This shows the last time the TODO line was modified, ie: it may have been created 10 years ago but somebody modified the last yesterday
edit: one might want to throw in --cached to git-grep to search the index and not just the current working-tree