This week, our office is being remodeled.  Not just adding a couch here or a plant there… entire walls are being knocked down and the concrete floors are being cut.  It’s loud and disruptive and the whole place is a mess.  Having a construction crew at work amongst a group of software developers has been an interesting experience.  These guys work with real materials.  They cut down real drywall and set real concrete.  We work with text.  We edit, copy and paste, undo, refactor, revert, save and compile. In the end, though, we do pretty much the same thing.  We’re both either working on creating or restructuring something to meet someone’s requirements.  Having these guys around has made me realize some things I’d forgotten about and a few things I’d never thought about before.


One of the first things I noticed was that whenever I walk past the area where the construction guys are working on, there are always blueprints around.  Serious blueprints, not just stuff scribbled in a notebook.  Someone had taken the time to document in great detail every angle and aspect of even the most boring places in our office.  How often have you ever seen such blueprint level detail in software design documentation?  It’s rarely done, and if it is, it’s rarely maintained.  There are many times when I wished I’d just done the work of writing down my thoughts as I coded, so that if I needed to revise that code in the future, I’d have a blueprint of what was there.  It’s obviously important enough for the construction workers to insist on, why not software engineers?  Most of the code I’ve ever seen or worked on is barely commented, let alone designed or modeled.

Diff, undo and revert

Of course, for construction, having the blueprint level of detail is essential.  For them, there is no Undo command.  If you’re cutting drywall and you saw through a main electrical line or cut a key structural support, there’s no way to easily fix that problem.  If there’s one thing I learned from watching “This Old House”, it’s that when you build something, you measure twice and cut once.  For us software developers, we have a whole arsenal of life saving techniques.  Diff, undo and revert are all things we do when we’ve gone down the wrong path.  I joke sometimes that I wish everything in life had an undo command.  Unfortunately, these things have also made us lazy (there, I said it).  Diff, revert and automated refactoring have caused many software developers to stop measuring at all before cutting.  Admit it, if compiling refactored code could potentially cause the roof to collapse, we’d be a lot better at verifying correctness by:

  1. Reading documentation and notes written by other developers whose functions and classes our code relies on.
  2. Documenting the functions and classes we write so that others will use them correctly.

These are easy things to do that can potentially save a lot of time in future coding work.

Frog in the Well

There’s a riddle about a frog trying to get out of a well who can jump up three feet, but then falls back two feet.  The more times you cut without measuring, or edit without designing, the more you increase the chance that you will make the wrong cut.  For construction workers, making a wrong cut is absolutely disastrous.  For software engineers, making the wrong cut means backing out and trying again.  It’s easy to forget that there’s a cost to reverting and refactoring; the time you spent writing what is being undone.  I’ve known software engineers that program like the frog trying to get out of that well.

Being able to back out of changes is a luxury that shouldn’t be taken lightly. There will always be times when it’s necessary, but it’s important to understand why it’s necessary.  The next time you have to revert or refactor, ask yourself how much time you lost writing the original code that had to be changed.  How much time could have been saved by designing the code before writing it.  How much time will be lost in the future if you don’t document why you had to revert or refactor?  If you wrote some code that you realized later was a mistake, what will keep other developers from making the same mistake in the future?

Don’t be the frog in the well.  Take a tip from our friends, the construction workers, and provide a plan for the code you intend to create or restructure.  Put it somewhere where everyone can get to it, and finally, tell everyone it’s there.  Not only will you benefit from the fore-thought of your design, but other developers will benefit from your insight before working on the same code.