Miyamoto Musashi for Web Developers

June 29th, 2015Giles Bowkett

Here’s an excerpt from an IRC conversation:

Senior Dev A: i was just reflecting on the fact that most of my “dev” time is having convos like this (design chats if you will), helping others, and not writing a lot of code. there is no need to write a lot of code. this is more like laser surgical strikes

Senior Dev B: When we design the project well, the complexity is distributed in such a way that bugs, features, whathaveyou are all easily handled with laser surgical strikes.

The instant I saw this, I thought of Miyamoto Musashi.

Musashi-sama was the greatest swordsman in the history of Japan, and wrote an excellent book on swordsmanship, martial arts, and philosophy: 五輪書, or The Book of Five Rings. This book lays out the fighting style Musashi developed, a two-handed style. In one hand, the fighter holds a katana, a traditional samurai sword; in the other, a wakizashi, which is basically a shorter version of the same thing. A major theme in the book is when you use which sword, and why. Most translations use “the long sword” and “the short sword” instead of the literal terms.

Picture by Joe Allen

Today, of course, we don’t usually talk about using a sword, even when we use combat metaphors. We talk instead about laser surgical strikes, because we live in the future, not a bygone feudal era. But a laser surgical strike is a very precise equivalent to the long sword; it’s the weapon you use at leisure, from a distance, with precision.

By contrast, when you’ve got a server crash and you’re writing hideous code in a hurry to put out a fire, that’s the short sword. It’s what you use in when you’re in trouble, up close, where the most important thing is not precision but speed. A modern equivalent might be mace or a sawn-off shotgun (particularly if you’re drawing your metaphors from zombie movies).

Building software isn’t fighting, and there are obvious downsides to overusing violent metaphors. But The Book of Five Rings is a terrific book about solving problems, and it pretty much divides all problem-solving into the problems you solve at a distance, with precision, and the problems you solve up close, as quick as you can.I’m overgeneralizing, of course, which is why you should read the book.

When web developers talk about solving problems, we often talk about why it’s better to just ship something than it is to cook up some imaginary perfect system. That’s the short sword.

Or we often talk about the value of elegant solutions, without acknowledging the sacrifices that elegance requires: it slows you down, and distances you from the problem. That’s the long sword.

Although any experienced developer will readily admit that you have to balance the need for speed against the long-term benefits of a clean design, few people talk about how to find that balance. And of the few who have discussed it, none do so with the clarity or insight that Miyamoto Musashi uses in The Book of Five Rings.

I say this as somebody who’s read not just many books on software development, but also many of the classics of Western civilization, often in their original languages. In Greek, I’ve read Aristotle, Herodotus, a little Xenophon, and bits and pieces of some early religious texts (although Homer, Sophocles, and Plato were all over my head). I’ve gotten through Cicero and some Caesar in the original Latin, and even managed a few lines of Neruda in the original Spanish.

What I’m saying, basically, is that I’ve read a lot of books, and The Book of Five Rings stands with the best of them. It’s a really good book. But hopefully I can rescue this post from my self-congratulatory digression by bringing it back to web development. Recall the conversation we started with:

Senior Dev B: When we design the project well, the complexity is distributed in such a way that bugs, features, whathaveyou are all easily handled with laser surgical strikes.

Our senior dev is here unwittingly paraphrasing Musashi, who said that you should make every fight a long-sword fight if you can. The reason is simple: you’re farther away from your opponent. Your risk of dying is smaller that way.

Again, please take these violent metaphors with a grain of salt, but complexity is the biggest threat to any ongoing software development effort. Good design allows you to keep that threat at arms’ length from you at all times. One important difference between experienced developers and inexperienced developers is that, all other things being equal, experienced developers will opt for problems they can solve at a distance, with precision, over problems they have to solve in a hurry, up close.Another important difference is that, ideally, experienced programmers will have learned the design techniques which enable this distancing in the first place. One hallmark of inexperienced engineers is that they will implement some classic idea of computer science, but misidentify it as some other classic idea of computer science. As an example, consider the way the Rails web framework embeds an almost textbook example of the Factory pattern in its inheritance mechanisms. Although nobody would deny that Rails made web development easier and quicker, if you want to learn from its successes and apply its lessons elsewhere, it helps a lot to correctly identify and understand how it works.

Sandi Metz, in her book Practical Object-Oriented Design in Ruby, said something very similar. Caveat: these days I personally prefer functional programming in JavaScript over object-oriented programming in Ruby. And Ms. Metz’s book lays on the Ruby mantras a little too heavy for my personal taste:

We can enjoy the pure act of writing code in sure knowledge that the code we write has use. We produce things that matter. We are modern craftspeople, building structures that make up our present-day reality, and no less than bricklayers or bridge builders, we take justifiable pride in our accomplishments.

It’s hard for me to read something like this without rolling my eyes. Nonetheless, when I mostly wrote Ruby, I probably said things like that far more often than Practical Object-Oriented Design in Ruby doesI can almost guarantee that a blog post comparing software design to martial arts will trigger some eyerolls somewhere., and the book’s still excellent overall. In this excerpt, Ms. Metz basically argues in favor of the long sword over the short sword:

Applications that are easy to change are a pleasure to write and a joy to extend. They’re flexible and adaptable. Applications that resist change are just the opposite; every change is expensive and each makes the next cost more. Few difficult-to-change applications are pleasant to work on. The worst of them gradually become personal horror films where you star as the hapless programmer, running madly from one spinning plate to the next, trying to stave off the sound of crashing crockery.

The type of problems you have to solve quickly, in proximity, are inherently more stressful than the type of problems you can solve from a distance, with some control over your own schedule. You should be good at both, but one category’s clearly preferable. That was true for Musashi, who had sword-related problems in each category, and it’s true for us, when we have application development problems in each category.