I found this list buried in my notes from long ago. I cleaned it up and updated it, but yeah, I still found wisdom in this advice from my former self.

Moreover, this advice is also to myself. I need to be reminded of these guidelines, as I sometimes disregard them and then need to go back and clean up things afterward.

I’ve been wanting to set up a software-development blog for some time. And for some time I’ve been wrestling with the pains of managing multiple WordPress blogs. Back in the day, when I had just my writing blog and a LiveJournal, it wasn’t such a big deal. Since then, I’ve retired the LiveJournal—sorry, LJ friends—and have set up a number of other WordPress sites, for different niches in which I write. In particular, I have a personal blog, a political blog (because I decided I should not pollute my personal blog with political posts), and now a software-development blog (which you are currently reading).

When I spun off the political blog, I got a taste of what it meant to migrate posts from one WordPress instance to another. And my experience with this SD blog was ten times worse, because there were 10 times as many posts involved.

The short version of the story: WordPress is broken, and it will always be broken.

The long version of the story… is a little more of an acerbic joke.

It’s like playing football. No one person can win the game on his own. Each player does his part to determine whether the team moves forward. The center snaps the ball to the quarterback, who hands it off to the half-back, who runs through a hole the offensive line has created in the the other team’s defenses. Or maybe the quarterback passes the ball to a receiver. Occasionally, the receiver is on a different page than the quarterback, and when the ball is thrown, there’s no one there to catch it. The play falls apart. Players either work together, or they lose the game. In football speak, this is called “not executing well.”

Good code, yes, has grace and beauty. But what makes it worthwhile is that it’s easy to work with. It’s easy to add to good code. It’s easy to take away. It’s easy to make changes. It’s easy to fix bugs. And bugs are rare. Good code does what you want it to, usually the first time. Good code is a joy, not a burden.

This should be the normal state of software. How many developers live in the opposite state? They think that adding a feature always takes a long time and many lines of code. They think that getting cozy with your debugger is part of the process. They think that long hours sitting in front of the computer screen means you’re doing your job. It doesn’t. Long hours means you’re doing your job poorly.

Consider these truths of quality code. The best developers know them without thinking. To them, good code is second-nature. They’ve internalized these truths. They’ve reached nirvana. They are one with the code.

I’ve been meaning for some time to write this. It took Lidor Wyssocky’s latest blog post to push me into it. And just in case someone out there couldn’t tell you were joking… (You were joking, right?) The sad truth is that “quick and dirty” may be dirty, but it’s never quick, at least not if you actually want to deliver a usable product.

The old comment for a struct declaration:

// This structure will be generated
// and stay with each connection

The new comment:

A good software design minimizes the time required to create, modify, and maintain the software while achieving acceptable run-time performance.

This definition has some pretty obvious, radical, and cool implications. Quality depends on what changes you’re making to the software and who is making them. How much time you’ll have to spend maintaining the code is more important than how much time you spend coding it in the first place. And all of this means you can’t plan ahead for design quality!