Darth Vader’s Guide to FIXME and TODO comments

There’s an ongoing debate in the developer community about the value of TODO comments in code. Just search google for "TODO comments" and you’ll find some good arguments for and against the practice. The fact is, developers have been doing this for decades and it’s unlikely to change anytime soon.

The same year Star Wars hit the big screen, Applesoft BASIC was intorduced in ROM on all Apple II computers. Imagine the TODO and FIXME comments Darth Vaders imperial engineers would have left if the Death Star code was written in Applesoft BASIC.

1000 REM TODO: Monitor radar near thermal exhaust ports
... (A few hundred lines of code)
10000 REM FIXME: A well planned attack of thermal exhaust port may cause a chain reaction that will blow us up
... (A few thousand lines of code)
100000 REM TODO: Close and open thermal exhaust ports at random
... (Tens of thousands lines of code)

It’s a good thing Darth Vader didn’t have the tooling we have today for organizing TODO comments in code. If he did, the Death Star would have destroyed the forest moon of Endor. This is what Darth Vader would have seen if his imperial engineers were using iMDone.

To-Do List Apps Suck!

I’ve fought with To-Do list apps for over a decade and my conclusion is, they suck. It’s not the user interface, the flow, lack of syncing between devices. None of that matters. I bet you still use a pen and paper to jot down tasks. Am I right? Even though you probably use an app for tasks, you still use that pen and paper. I do too. The problem with to-do list apps is that they’re not pen and paper. When you realize you have a task to record, you have to go into the app and record it. Pen and paper is simple. Pick up your pen, jot down the task and get back to work. Most people use pen and paper and a to-do list app, writing down their tasks on paper and when they have a break, entering them in their to-do list app. If you don’t, then you’re probably a purist who can’t function without a device and struggle to get things done.

Developers

For years software developers have been keeping track of to-dos in their work. For example if I’m working on a piece of software and I realize something’s broken, I don’t stop to open my to-do list app. I just place a comment like this in my code.
// FIXME: Make this change so the code isn't broke

Then I continue what I was doing and look for all the FIXME comments with grep or use my IDE to list them. Recording tasks this way allows a developer to stay focused on their current task, but record something they thought of outside the context of their current task. Now I just have to use grep or my IDE to find my tasks. But now I’m overwhelmed, because I have hundreds of TODOs and FIXMEs in my code. What do I do first? How do I keep from getting overwhelmed? How do I prioritize my work?

iMDone

I’ve tried dozens of to-do list apps, used grep and IDEs, but I couldn’t find the right combination of tools to keep my focus. So what does a person do? I’ll tell you what I do. I use an app that helps me stay focused and keep from getting overwhelmed. It’s called iMDone and it does this by letting you hide the distraction of things you haven’t done and allows you to move your tasks in and between lists while keeping them in sync with your code. It can find tasks in any text file, so if you’re a blogger and use markdown or plain text to write your posts, then it’ll work for you too.

Help me help you

For me, this isn’t enough. I’d like to be able to record a task no matter what I’m doing. From anywhere on the web, or from any app. Developers have been recording tasks this way for decades, but anyone should be able to do it in any file, in any app or on any website they use. Help me get there. Help me help you.

Flattr donate button Support via Gittip

iMDone - Keeping tasks where they belong

Have you ever been in the middle of a project and wanted to jot down a task related to the file your working in? Some of us will just type it right there. If it’s code we use a comment prefixed with a big TODO like this.

//TODO make this code a little cleaner

Or if your writing a blog post, you may use a block quote, or worse yet, you leave what your doing and lose context by switching to a task management app. I have nothing against these apps, they’re great at what they do, but when I’m hard at work on something like code or a blog post, the last thing I want is to lose focus.

I’ve been hyper focused on this problem for the good part of a year now which has resulted in the LeanNotes app. I’ve even been using LeanNotes to keep track of my development tasks for LeanNotes. How’s that for scratching my own itch! But wait a minute… I broke my first rule. Don’t lose context. When I jump out of my code to record a task in LeanNotes, it’s a distraction and I lose precious time and focus. So what’s the solution?

I’d been working on some much needed changes to LeanNotes when I read Open Source (Almost) Everything by the co-founder and CEO of github, Tom Preston-Werner. I didn’t have something I was currently working on that made sense to open source, so I decided to tackle my context switching problem and start iMDone.

As of this writing iMDone is 16 days old. It runs on your machine as a nodejs app. It’s not a website that you have to log into, or even be on-line to access. What it does, is read your local files starting in a directory of your choosing and pulls out tasks you’ve created by using a markdown link syntax like this.

[Make this code a little cleaner](#to-do:0)

If you know markdown, you recognize the text between the square brackets is the link text, but the link url is special. It consists of a # followed by the list name which is followed by a : and a number to sort the task by.

When you start iMDone it recursively reads the current working directory and pulls out anything that looks like this in files and sorts them into lists. When it’s done, it opens a local web page that displays the lists.

When a file changes that iMDone thinks might have a task in it, the page is instantly updated. Pretty slick you say? Well, It doesn’t stop there. You can drag and drop tasks from list to list, re-order them and change the list names. All the while, iMDone is updating the files with this information so it stays in the code or files or whatever.

Here’s a bonus. Since iMDone is file based and it only adds a single directory and two small files to the current working directory, you can keep it in git or dropbox or svn or cvs or… you get the picture. Tada! Problem solved. I don’t have to lose context AND focus AND time to track my tasks. And I don’t even need an internet connection!

Markdown and Kanban sitting in a tree, KISS…

KISS or “Keep it simple stupid”, is what I remind myself when things just aren’t working. And simplicity is what I found when I combined Markdown with a Kanban board.

I’d been searching for the best way to keep notes and tasks for a long time. Working in IT for an apparel company, we have a large number of projects running at any given moment. I’m also a father of three very active boys, an owner of a hobby farm and a bootstrapping entrepreneur. Too much you say… your right, but I’m a glutton for punishment so I sink serious time into managing my work.

Over the years I’ve tried keeping notes in good old fashioned notebooks, text files on the computer, the now defunct Google notebook, wiki’s, Evernote and a few other apps. All of these worked well for keeping notes, but I liked wiki best because I don’t like taking my hands off the keyboard to format text. So over time I settled on using a wiki to keep my notes. But I still had the problem of managing tasks that I jotted down while taking notes. Managing tasks has always involved too much work. I like doing stuff more than managing it. If I was disciplined, at the end of the day I’d read through my notes and pick out the tasks and action items. At first I’d jot them down on a separate sheet of paper. I wound up with notebooks full of tasks in priority order, until the priority changed! I also tried managing them electronically with apps like Remember The Milk, Google tasks, outlook, spreadsheets, and the like. I even sent myself emails with lists of tasks to accomplish the following day. It was a big hassle and I would have to riffle through my notes again to remember what I was thinking when I created the task. What I needed was a companion app called “Remember the notes?”.

About 2 years ago I discovered Kanban while investigating Lean process. This discovery lead me to tracking my tasks in tools like Kanbanpad, Trello or just a white board with columns of sticky notes. I like the idea of limiting my work in progress. It helps me keep focused. Kanban helped me accomplish the most important and urgent things first and reorder tasks easily, but I was still looking through my notes to find the bits of information that would help me complete my tasks.

Then I thought to myself. Why can’t I keep my tasks in my notes? Why do I have to write them down or key them in twice? Why should I have to hunt around for the information I recorded in my notes when I’m trying to get stuff done. I went to my best friend Google to find an app. Come on, there has to be an app. Nope, no such luck. Well, being a developer I sat down and started coding. Actually I was standing, but you can read about that in "A morphine induce startup". LeanNotes was born. Now I keep my notes using an extended version of Markdown. If your not familiar with Markdown, follow the link. It’s good stuff. The special sauce provided by LeanNotes is the task syntax, so when you save the note the task gets an id and links it back to the note. Once the note is saved, you just click the task text and it takes you to a kanban board. I use it every day. I’m even using it right now to type this post.

Here’s an example task:

- [Publish **Markdown and Kanban sitting in a tree KISS...** to tumblr](t#doing)

Maybe LeanNotes can help you KISS!

A morphine induced startup

How many of you have experienced drug induced startup ideas? Come on be truthful. It happens all the time. Some of you with alcohol, some; other things… I had one about a year and half ago.

In May of 2011, while working my day job, keeping up the farm and coaching my son’s soccer team I had been working on a site that brought the experience of a flea market to the internet. I had a lot on my mind and tons to get done. But I always make time to blow off steam and play some soccer. That’s when it happened. I felt tightness in my leg after playing futsal (a form of indoor soccer). Then a few days later, after a practice with the boy’s, I drove them to my mother-in-law’s house and got out of the car. I could hardly stand up without excruciating pain. I had sciatica. For the next several days I couldn’t even lay down. So I didn’t. I walked around pacing and cursing.

Now I was in major pain. It felt like someone was literally sawing my leg off, so I went to see the doctor. He gave me slow release morphine. Unfortunately I still couldn’t lay down to sleep so I decided to get some coding done. In a bit of a haze, I opened my laptop, put it on a chest of drawers that allowed me to stand while typing and got to work on the flea market site. I went into my kanban board and looked for what I should do next. I felt overwhelmed. I was missing work and falling behind, but I had to do something to help distract my mind from the pain.

For years I had been searching for the right tool to keep track of tasks and a tool to keep notes. I’d tried plain old wiki apps with lists, to do list apps, text files, google notepad and tasks, outlook, text files for notes and lists, remember the milk, kanban boards… You get the picture. I t just wasn’t working out. So while I was standing there, my mind somewhat calmed from the morphine, I came up with an Idea. I was going to scratch my own itch and create what I had been searching for but couldn’t find.

I love Markdown. In fact, I’m using it now to write this post. It’s simple yet effective and my hands never need to leave the keyboard, so it’s great for keeping notes. But I had another problem. Every time I needed to record a task, I had to leave my notes and open another app. “No problem” you say, “I do the same thing”. But I didn’t want to leave my notes, wanted the tasks to be linked to my notes and like using kanban. Nothing I could find up to that point could do this. That’s when LeanNotes was born.

I decided to get it done. Now would be the time. I downloaded mongodb and showdown.js and got to work. By the end of the first night I had created the note taking app. It took a few days to get it to the point where I could use it daily, but I was still keeping lists of tasks in each of the notes. I was even keeping a list of features for LeanNotes on a single note with three sections “Doing”, “To Do” and “Icebox”. It was getting hard to handle.

By now the sciatica was starting to subside and I returned to work. I used LeanNotes every day to keep notes, but I was missing things. I never knew what I was supposed to work on. All these lists took more time to manage, and I had too little time to manage them. So I got to work on the task management features. I decided to use the link syntax in Markdown for tasks with a little twist. A task would look something like this:

- [My history using to do lists and the creation of leannotes](t#to do)  

This would put a task in the “to do” kanban queue or bucket as I call them in LeanNotes, and have it linked to the note. After saving the note the task would appear the same in the Markdown except a uuid will replace the bucket name. like this:

- [My history using to do lists and the creation of leannotes](t-88289f58-980d-492d-8d2d-1cf3fb86394a)  

On the tasks view it looks like this:

So there you have it. A morphine induced startup called LeanNotes is born! Try it out. It may scratch your itch too. If it doesn’t you can always try an antihistamine.