Creating a ticket is easy when you are in the moment. However, once produced these artifacts have to be read and understood multiple times in the future. Each time you read a ticket it costs time. How many times have you given up trying to find some ticket that you think you wrote a long time ago and just entered a new one? How much time have you spent sifting through the same tickets every iteration deciding repeatedly that they are not important enough to actually schedule?

I am not saying that you should not enter tickets in your issue tracker. I am saying that doing so is not free. Therefore, you should consider very carefully whether the story or bug you are about to write will have a net positive value over the life of the project. Most likely it will not.

My rule of thumb is this: do not write it down unless you are willing to schedule it right now.

Willingness to schedule a bit of work is proxy for its importance. It is easy to pretend everything is top priority. If you are not willing to prioritize a bit of work before something you have already decided you want, it is obviously not very important.

If it is important you will not forget

I think the idea that you will forget something important is the scariest part of this approach. That fear is just silly. If you are passionate about an idea you will not forget it. If it is important to your customers they will not let you forget it.

Let me ask you a question: if neither you nor the customers care enough about an issue to get it on the schedule should you be expending effort on it?

To me the answer is clearly no. If you see a potential issue or have an idea let it rest until it becomes important. Odds are it never will become important and you will have saved a good deal of every one’s time. If it ever does become important the fact that six months ago you wrote a ticket vaguely related to an issue people are having now will not help anyway. You probably will not even be able to find that old ticket.

Corollary: todo comments considered extra harmful

Notice that my rule of thumb basically rules out todo comments altogether. Every todo comment is not only an unscheduled story, but an unscheduleable story. Even if the todo comment were a story in the ticketing system it would never, ever be scheduled. If it had a chance the developer would have written a story instead.

Todos are far worse than mere unshecheduled stories. Todo comments are a way for the developer to transfer some of the weight of the decisions that they made to future generations. A tax, in effect, on future generations of developers in order to assuage the author’s insecurities regarding decisions they have made in the code.

To the authors of todo comments i say, own your decisions. If you are not sure of what to do get a second pair of eyes now. Whatever you do, don’t burden future developers with your indecision. Right or wrong it will work out better if you make a reasonable decision and own it until there is some evidence that it was wrong.

The usually suggested way to handle this is with git-stash. For a long time, i used stash in this situation myself. However, i often found myself lost in the stash queue. If you use stash to store unfinished work your stash queue can become quite long. It is easy to forget you have stashed work. It is also easy to do a git stash clear and lose that work.

There are lots of situations in which it can be quite a while before you get back to your stashed changes. For example, if you switch tasks because the business deprioritized the feature. Or if the urgent issue gets interrupted by an emergency issue.

It recently occurred to me that git provides a much more elegant way to deal with unfinished work.

The steps

First, always work in a feature branch. You should be doing this anyway but it is required for this technique to work.

1. git add -A (on the feature branch)
2. git commit -m 'WIP'
3. Switch branches and fix that urgent issue. Using git like you always do.
4. git checkout <feature-branch>
5. git reset HEAD~1
6. Continue where you left off. Once you are ready, commit.

This approach commits you in-progress work on the branch to which it belongs, keeping it safe.

How it works

Once you do your WIP commit your history will look something like:

That is great for temporarily storing your in-progress work. We definitely don’t want that nasty “WIP” commit in our history long term, though. The git reset HEAD~1 command changes the HEAD pointer of the feature branch back to the commit immediately before the “WIP” commit. That leave a commit graph something like:

Once you have completed your changes and committed the HEAD pointer of the feature branch will be updated to point the new commits. This leaves the “WIP” commit out of the commit history of the branch forever.

The “WIP” commit is now “unreachable” because no objects or references in the system point to it. It will be removed the next time you do a git gc.

git stash definitely has it place but i reserve it for situations where i am going to pop the stash very quickly (eg, i stash, the checkout a different branch, then pop).

I going to Mountain West RubyConf this weekend. I am very excited. Last year this was a great conference and the schedule looks great this year too. If you are going to be there too let me know. One of the great things about these conferences is all the great people you get to meet, so hopefully i’ll see you there.

The job I left was as at Absolute Performance, and it was a pretty good gig. The good news is that my leaving means that there is a spot for you. If you are interested in working on some cool Ruby, Java and C++ code with a really great team you should send them a resume. Oh, and don’t forget to tell them I sent you, maybe they will buy me a lunch or something.

With today’s connection characteristics, I wonder if HTTP would have been the weapon of choice 15-20 years ago? I doubt it.

Based on this conclusion Jud appears to believe that XMPP will replace HTTP in the future as the protocol of choice. I disagree with Jud on both points.

The Internet is much more reliable today than it has ever been before. It is so good, in fact, that there are many situations where you can trust the network these days. This is particularly true high levels of reliability are not required. However, the network is still not perfect, nor is it likely to ever be. Worse yet, the software that uses the network is still depressingly flaky.

More importantly, I don’t think HTTP “won” because of problems with the network. HTTP is ubiquitous today because it facilitates a programming model that can the use to solve some really hard problems reasonably easily. That programming model an implementation of the REST architectural style. The constraints of REST allow building highly scalable and reliable systems far more easily than any other approach available today.

In his post Jud speaks of HTTP as if it where transport protocol. As a transport HTTP is not terribly compelling. It has fairly high overhead for individual requests. It’s connection model usually ends up creating more TCP connections absolutely necessary. It allows a lot of variability in the capabilities of clients. And so on.

However, HTTP is decidedly not a transport protocol. It is an application protocol. HTTP provides a sophisticated set of semantics specifically designed to facilitate the implementation, and optimization, of REST style applications.

XMPP is, on the other hand, is a transport protocol (unlike HTTP). To be precise it is a (near) real-time message transport protocol. If you need that XMPP is an excellent choice. Particularly if the messages you a dealing with have a limited duration of meaningfulness. For example, if your application loses it’s connectivity to the message sender for any significant period of time it is likely that the application will not receive at least some of the messages sent via XMPP during that time. The server may spool some messages but completely unreasonable to expect APIs to keep track of an arbitrary number of undelivered messages for an arbitrary number of clients. The cost of doing that are just too high for a high volume producer to be able to implement.

I think XMPP will continue to get more penetration and mind share. It is a good protocol. It is not a competitor to HTTP, though. The two protocols serve very different purposes. I expect that many systems will utilized both. If you have a need for real-time messaging and you have relatively weak reliability requirements, or you are willing and able to invest significant effort implementing reliability in your application, use XMPP. But real-time messaging do not an application make.

HTTP is not a “dinosaur”, as Jud puts it, it is a shocking advanced piece of alien technology we have only recently discovered (as an industry) how to fully utilize. Actually, I am pretty sure we have not yet figured out how to fully utilized it. We will continue to see more and more applications and data service APIs implemented using the wicked cool semantics of REST/HTTP.

My family and I are vacationing this week in San Diego. So far it has been pretty much perfect. Weather is really nice, if a bit cool for swimming. Our condo is nice and well located (a block off Mission Beach). The kids like the water, but the sand is where the fun really is as you can tell from the picture above.

So, commercial revision control vendors, let me clue you in. Revision control systems are not the center of the software development universe, the file system on the developer’s machine is. Period. The primary job of a revision control system is to figure out what the developer did, after the developer has already done it, and to save that so that it can be applied to the other developers local file systems.

I am complaining about this because out of the box Perforce does not include a way to examine your working directories and get a list of what has changed since the last time you synchronized with the depot (Perforce’s word for a repository). This means that you must declare any changes you make to the source code tree before, or at the same time as, you make them. If you do not declare the changes up front it is almost certain that some required changes will be forgotten and will not get checked in.

The main problem with this approach is that it compels you to break your flow. You might not think that just having to execute one additional command would really be that bad. After all, executing a command could probably be incorporated into your personal process and thereby have little or on impact on your flow. In practice, however, it really does break the flow.

The true cost of declaring that a new file will exist with a particular name is not in the act of declaration. Rather, it is in the thought and commitment that such a declaration requires. Every day, I created new classes only to notice a couple of minutes later that it has morphed in to something quite different than what I originally intended. Declaring the name of a new file to the revision control system before I have even created it dramatically raises the cost of such emerging behaviors. To name a file well I need to understand it’s purpose and to do that I usually need to create it and put some code in it to see how it turns out.

Having to declare the name of the file first requires a significant amount of thought and, worse of all, it prematurely solidifies the design. This premature solidification of design is costly both in terms of the time it takes and the quality risks it introduces. Paul Graham makes a compelling case for a fluid approach to software design in Hackers and Painters. Forcing stability on an immature design merely locks in its deficiencies and that is exactly the result of requiring the declaration a file before it is created.

The need to declare modifications and deletions up-front is less onerous. Deletions are easier because, generally, it is easy to understand the consequences of deleting a file because there is only one. Modifications are easier because marking a file at “to be edited” is quite forgiving. Even if you failed to actually modify the file checking it in will have no functional impact. None the less, having to declare you intentions up-front is still annoying, and wasteful since they could be determined after the fact.

If you are a commercial revision control system vendor please take note. You are not, nor will you ever be, the center of the software development universe. Pretending that you are just costs your users time and effort that could be better spent solving real problems.