Deciphering
Glyph
( )
Ultimate Quality 功夫 System

Fri 15 June 2007

Often it is the means that justify the ends: Goals advance technique and technique survives even when goal structures crumble.
- Alan Perlis, Epigram 64, "Epigrams in Programming"
How does a computer programmer get better at computer programming?

In a very broad sense, there is some consensus on the answer to this question.  It's like the answer any other skill.  "Do a lot of it."  Much like other skills, though, while necessary, this condition is not sufficient.  If you want to get really good at punching, you can punch a brick with your thumb inside your first ten thousand times, and someone who has learned to do it correctly and had a fraction of the equivalent amount of practice will be a lot better at punching than you.

So, to expand on that consensus, to get better at programming, you have to learn to do it right, and then do a lot of it, hopefully with someone correcting your mistakes and helping you do it better each time.  Like any other kind of serious training.

This concept is pretty old.  Shortly after the dawn of time, the dragon god-emperor pioneered this concept when he invented a martial art that is now popularly known as "Kung Fu", or, literally, "achievement through great effort".  The term does not necessarily refer specifically to martial arts, and can (in both Chinese and English) refer simply to the fact that someone has achieved something exceptional through a lot of effort and practice.

Specious metaphors between computer programming and martial arts (and various eastern philosophies) have existed for almost as long as computer programming itself.  As a cocky and callow youth, I occasionally had these metaphors generously applied to me, but they rang hollow even in my hubristic state of mind.  I knew that despite any talents I might have, at the very least, I hadn't spent a lifetime of effort achieving a near-supernatural mastery of computers.  I had just messed around with C++ and Java a little bit.  The appellation of "master" was inappropriate, but I didn't know how one really did go about getting to that point.  I had already met a few folks in the programming profession who were old, but certainly not yet wise, and I wanted to learn how not to end up like that.
Whenever two programmers meet to criticize their programs, both are silent.
- Alan Perlis, Epigram 101, "Epigrams in Programming"
I first noticed that the parallel between UQDS and these various arts and philosophies when a friend observing Divmod from afar mentioned that our review process was intimidating.  Intrigued, I conducted a straw poll among my programming friends who are not deeply immersed in the eternal struggle of the Twisted or Divmod codebases, and found that there was a fairly consistent impression: the exchange of comments between authors and reviewers was highly unusual, intimidating, and impressive.

It's unusual because most people cannot read code well enough to comment in as much depth.  Code review is becoming more popular, but it's still rare.  Even intense, newfangled "Agile" processes like Extreme Programming focus more on discussing code as it's being created than reading code which has already been written.

The exchange is intimidating because many of the comments are extremely fine-grained and not very forgiving.  It isn't uncommon to see comments about a tiny private method missing documentation, or test coverage doesn't hit a single error condition.  This causes the reader to muse on the ways in which their own code would fail if it were subjected to such intense scrutiny.

Finally, the exchange is impressive because the factors which make it intimidating make the programmers doing it seem extremely skilled.  If you're looking at work which is being subjected to criticism only on details which seem insignificant, it implies that it is in every other way correct.  To some extent this impression is illusory, because the reviewers are only human and may be missing more important things.  For something as complex and intricate as software, though, it's impressive assuming that the reviewers tried at all.

I can't pretend that UQDS is an entirely unique process in this regard.  The Python and Subversion projects practice regular code reviews in public, and those are just the ones I know off the top of my head.  This isn't a phenomenon unique to open source either - I know that both Canonical and Google do fairly comprehensive code review on their closed-source products.  I've heard milder expressions of awe - although perhaps they were only milder because they came from friends - about those projects and companies.

While it isn't unique, UQDS is particularly intense.  Some other processes try to be "reasonable" - which is, on the face of it, a reasonable thing to do.  Small, "obviously correct" fixes are sometimes allowed without tests.  "Security" fixes are sometimes allowed in for expediency because of their urgency.  Some committers are sometimes exempt.  Some reviews are done after the fact.  Documentation is often optional, since reviews are meant to enforce correctness, not every aspect of quality.  For better or worse, UQDS sets out a much stricter guidelines: everything must be tested.  Everything must be documented.  Nobody is allowed to bypass the process.

It isn't all roses.  Especially when a contributor needs to update an area of code not originally developed under this regime, it can be frustrating to need to document and test and correct code that isn't really related to their goal.  Sometimes the overabundance of the opportunity for review creates interminable discussions about a design, when there is really a need to just go with a solution that works for now.  There may be some room to adjust the constraints to place less of a burden on those who want to contribute small improvements, and that's difficult without compromising on overall quality.

Despite their drawbacks, these rules plus a public ticket tracker add up to something that the industry of martial arts has known about the power of for quite some time: the exhibition.  If you're going to run a martial arts studio you need to attract students, and to do that you need to "wow" people every so often.  Martial arts are about defense, mind-body integration, health and fitness, and self-discipline, but putting that on a poster isn't going to fill up the thursday evening class.  Sometimes you need to get your school together and show off just how bad you would be able to kick some ass with your skills, you know, just in case anybody was wondering.

I am quite proud of the fact that I've received numerous unsolicited comments about the quality of the code itself within certain parts of Divmod and Twisted.  Like any programmer I've received my share of complaints about my work, too (especially the stuff that precedes all this intense review), but as Steve Yegge famously observed, most programmers who are famous for their programs don't actually write programs; they write about programs, or they wrote some programs nobody has the code to.

I'm almost more pleased with the idea that I could help pave the way for programming to have some real rock-stars on the merit of their code than the idea of being a rock-star myself.
Dealing with failure is easy: Work hard to improve. Success is also easy to handle: You've solved the wrong problem. Work hard to improve.
- Alan Perlis, Epigram 101, "Epigrams in Programming"
To close, there are a couple of skills that I think UQDS promotes which there might be other ways to promote.  If you want to develop a competing "school", these are things to think about:
  • Reading code.  Open source is great because you can read the code, but UQDS gives you a reason to do the reading.  Not just skim, not participate in the writing, but really read and analyze.
  • Communicating with other programmers.  Another thing that UQDS has in common with a martial art is that it's adversarial.  You throw the "punch" of a patch, the reviewer "blocks" with a branch, and so on.  You don't need to be a social butterfly to get this right, but you do need to be very focused on the technical communication skills required to explain your ideas.
  • Testing.  Test-driven development is an excellent trend.  UQDS doesn't have much to add to that beyond enforcing it, and making the application of TDD the easiest way to get through reviews which deal with issues like test coverage.  (If you test everything before you write it, of course your tests are going to cover everything before you put it into review.)
I'm not a martial artist.  The closest I've come was years ago when I was a fencer, and although I hope to pick up a sword again some time soon, I am no expert.  Still, I have a great deal of respect for Kung Fu, and I hear a fair amount about it from a fellow I know who did some training in it, and I think this is a bit more accurate of a comparison than the earlier attempts that I mentioned; so if you're a twelfth dan grand master in ultimate ninjitsu, please don't explode my head with your psychic powers if you think I'm wrong.

A disagreement in the comments would be sufficient.