Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
100 lines (58 sloc) 11.3 KB
title: why write todo comments?
---
idx: 60
---
metadesc: sure, you've seen good comments, bad comments, api comments, even some other mysterious fourth comment, but have you seen unblocking comments? (probably)
---
content:
The other day while listening to [edge cases](http://edgecasesshow.com/111-here-be-dragons-style-comments.html), i was tickled to hear [wolf](http://twitter.com/rentzsch) talk about comments and how, as he's aged, he prefers really only two flavors of comments, API Comments/Documentation and [here be dragons](http://en.wikipedia.org/wiki/Here_be_dragons) comments. But sadly, he didn't mention the kind of comments i'm going to talk about here.
To begin, he cites [this gem](http://en.wikipedia.org/wiki/Best_coding_practices#Commenting) from wikipedia:
>Due to time restrictions or enthusiastic programmers who want immediate results for their code, commenting of code often takes a back seat.
At [work](http://www.khanacademy.org/careers), we have a slogan "[shipping beats perfection](http://bjk5.com/post/60760280107/shipping-beats-perfection-explained)"[^sbp] and it is much of the rationale for this other kind of comment, which i will call *the unblocking comment.*
[^sbp]: its background is this other phrase, *[bias towards action](https://dschool.stanford.edu/groups/k12/wiki/548fb/Bias_Toward_Action.html)*, which, to be honest, i don't think i'd heard until this past week. It is, however, an interesting cousin of the more contentious Worse is Better™[^wib]
### the unblocking comment
The practice, introduced to us via craig silverstein[^csilvers], (and to be clear, khan academy is *not* unique here) is to leave comments for the things you recognize are *probably* out of immediate scope and that you aren't able to get to right now so that you can *get on with your original commit* (i.e. unblocking yourself).
[^csilvers]: craig has been responsible for many fantastic process gems, so i feel very lucky to be able to crib this one from him almost entirely wholesale for my own [internet fame](https://www.youtube.com/watch?v=xdhLQCYQ-nQ) and glory.
let me show you a 'for instance' from my super hacky [tumblr editor](https://github.com/nsfmc/stumblr) package:
```python
# TODO(marcos): what if this also fails?
if more_info['meta']['status'] == 200:
post = more_info['response']['posts'][0]
# TODO(marcos): maybe check a pref for this
webbrowser.open(post['post_url'])
```
the two `TODO(marcos)` comments map to things that i might, at some point get to eventually, but that aren't truly 'blocking' or 'stopships' or whatever. They're basically baby yaks that if i'm not careful, might develop into full grown yaks[^yakshaving] demanding my attention and shears.
[^yakshaving]: ![](malcolm-in-the-middle.gif), [which see](http://raganwald.com/2014/02/28/a-programmers-story.html)
or more recently, this past week, while playing with [Framer](http://github.com/koenbok/Framer):
```javascript
// TODO(marcos): use cycle here
var collapsed = true
scrubBG.on(Events.Click, function(){
if (collapsed) {
// TODO(marcos): instead of just unclipping the layer
// animate the text in separately
```
And, to be clear, the code works! Right now! it's just that *if* i ever want it to work better or if i return to it, i have already outlined a roadmap for myself (or others) on how to do that. The framer code is *by definition* a prototype, so let's be honest, who cares if i'm using `cycle` correctly, but my intuition to Do The Right Thing™[^dtrt] is the sort of yak that might have wasted precious prototyping time.
[^dtrt]: i'm pretty sure spike lee never thought [his movie](http://en.wikipedia.org/wiki/Do_the_Right_Thing) would ever be referenced so often in terms of software engineering discussions
These todos, in the context of both projects, are the software development equivalent of a "[sweep](http://www.43folders.com/2006/07/24/b2gtd-mind-sweep)" in gtd[^gtd]. Which is to say, that in writing the todos, i've explained what i need to do (but i can't do right now), and by doing so, i've absolved myself of the guilt of doing it *this very minute.*
Allow me to repeat: by leaving the `todo()`, i communicate to others (or future-marcos) my understanding that the problem exists but that rather than investing time in writing possibly unneccessary code, *i am moving on.* In the present day, it gets me unstuck and moves me forward towards a working implementation that i can nit-pick later.
Again, i'm *not* promising work on the femtoyak right now, i'm not even committing to it in the future (as my tumblr comments have borne out)—i'm doing two things: publicly acknowledging the issue *exists* and punting it so that i can get on with my day. Why even put my name on it, you ask? If somebody does get around to it, they know exactly who to ask for more detail! I'm happy to help them!
Most of you are shouting at your monitor saying that this is like time-management 101, but it took my subconsciously creating these `todo()` comments to get me to *truly* internalize their [real ultimate power](http://en.wikipedia.org/wiki/Real_Ultimate_Power).
[^gtd]: A sweep, briefly, is this nifty idea where in order to be able to prioritize all the task you possibly have, you put everything you can think that *might* be a task into a task list. By moving all those ideas out of your head and into a place you're likely to look at later, you allow your mind to only wander to tasks that are relevant *now.* gtd® is [copyright](http://www.5by5.tv/b2w) DavidCo 2001.
The novelty here, the point where this ties back to the quote, is that this is actually *the opposite* of the problem outlined in the wikipedia article. In my vim to get towards a working solution, i'm leaving important implementation and polish related comments for myself (and others) so that i can address it better... but only once i have something that merits fixing.
Just to be clear, though, if you have actual bugs that merit tracking, you really should find a way to get to those in a way that's higher priority than these `TODO()`s which really are historic context-rich vignettes of the rabbit-holes you've avoided. By all means, continue logging assertions and running unit tests for your bits that need to remain stable!
But... i want to repeat the central 'point' here which is that *comments don't have to take a backseat to getting things done*. In fact, i hope i've shown that, comments can provide a relatively easy way to get you from "zero to working"[^mvp] while providing a legitimate roadmap for you to get to something sustainably developed in the future.
[^mvp]: although philosophically aligned, this is *not* going to devolve into an essay about minimal/[maximal](http://www.allenpike.com/2013/maximum-viable-products/) viable products. phew.
### dealing with guilt
I've been trying to find a good way to end this essay, some sort of meditation on why something as mundane as a todo comment would even be necessary to write about. It took the span of a few weeks for the podcast gods to answer my call in the form of an [episode of ATP](http://atp.fm/episodes/95), going full-circle.
The episode is interesting because it deals with deeper issues of obligation and guilt in software development and maintenance. It's a highly relatable episode for anyone that has participated in the open source ecosystem. In particular, it pairs well with this 100% insightful essay called [Emotional Programming in Open Source](http://lucumr.pocoo.org/2013/11/28/emotional-programming/) by Armin Ronacher. You should definitely read it, but I'm going to pull a whole chunk of it here:
> I found it quite hard this year to work on my own projects because the bug trackers were full of things I personally did not really care about. The things I wrote over the last few years all work so well for me, that I don't need to fix problems or add things. When there is something that needs fixing, I will work on it, but otherwise I don't necessarily get the motivation to work on it.
> ... the whole porting to Python 3 thing has killed so much motivation for working on my project for me. I cannot use Python 3 in practice and having to deal with issues I don't have myself is one of the most frustrating things.
He calls out an important distinction between bugs which are currently breaking a build and in-utero yaks which shouldn't be on your radar just yet. Todos, in contrast, aren't traditional 'bug' reports, they're *opportunities;* for refactoring, future architecture changes, performance optimizations, etc. Maybe they're nice to haves, maybe you discover they're actual bugs: time will tell.
The effect of writing and revisiting `TODO()`s is better understanding the dynamic between problems you have *right now* and issues that are actually non-issues. If a todo lingers for a while, it's probably *not* an issue you really have and certainly not one that's keeping your project from functioning in the short term. Maybe if you're bored you hit it up. Maybe a contributor decides to attack it.
But the problem that many of us have, is that *we know* what The Right Thing *is* but our time and priorities are at odds with that. Does that choice make us worse programmers? Should it hold us up from [releasing a project](https://news.ycombinator.com/item?id=8132939)? Would it be better if we just pulled our project? No to all. It's a calculus of writing code, our time available, obligation to our code's users and our own guilt. Those are challenging things to balance!
[Developing software in the open is complicated](https://www.youtube.com/watch?v=0SARbwvhupQ) *even* when when you're bootstrapping it in private. But it gets more difficult if making progress is fraught with guilt and obligation to some all-seeing [Van Hœt](https://twitter.com/karlvanhoet). So many of these issues, these problems in casual development are complex issues of time management, guilt and obligation. Leaving todos can free you from worry and push you towards fixing issues you care about right now so you can start enjoying the software you make.
[^wib]: If you avoided that link soup but want to explore a decades old religious war, the idea is effectively '[worse is better](http://www.jwz.org/doc/worse-is-better.html).' In our case, it's more problematic to indefinitely hold back a feature that can have a better effect now because "it's not totally polished." Most importantly, it's admitting that getting bogged down in details doesn't always get you closer to the end result, and at worst, gets you farther from it. This isn't a hard and fast truth, some things *do* deserve more time, more attention, more care and craft. It's up to you, the reader, to determine which things merit that in favor of shipping a benefit to others *now.* I don't know of a good way to explain when that's an appropriate choice to make because *it totally depends on your situation.*
### thanks
it wouldn't be a *real* thousand word internet blog post without an artisinal colophon, so thanks for the feedback and comments: [@marcia_lee](http://twitter.com/marcia_lee), [@andy_matuschak](http://twitter.com/andy_matuschak), [@kamens](http://twitter.com/kamens), [@pgbovine](http://twitter.com/pgbovine), [@dmnd_](http://twitter.com/dmnd_), and [chrisklaiber](https://github.com/chrisklaiber) and [@dylanvee](https://twitter.com/dylanvee).
If you have any thoughts on this and have made it all this way, i'd love to hear from you. Feel free to send me an email.