Wipe Your Feet Before You Come Into My House

My code is my house. I spend a lot of time in it. I fix it up, take care of it lovingly. I indent appropriately and actually spend time spacing out sections so they’re pleasing to the eye. I do this only partly because I’m obsessive compulsive. My greater motivation is that I really feel that these things matter.

Think about the word “code” for a minute. I love the word. I am a coder. I write code. What is code? Code is something that means something to the person that writes it, means something to some people/machines that read it, but means nothing to people who don’t know how to read it. Code is inherently cryptic. So the act of writing code is a struggle against entropy. Over time the code’s intent will change, its implementation will be less clear, or its documentation will drift out of sync with the actual representation.

As when you move into a house, code will never be as nice as it is on day one. Something breaks and you have to fix it quickly, leaving a hole in the wall. People come to visit and leave their shit around. Perfect code never stays perfect. So it’s critical that on day one the code is as clean and clear as it can be. And you should expect to do periodic improvements to keep entropy at bay.

Speaking practically, this implies a number of things. First and foremost, formatting matters. Spacing matters. These things help someone else determine the intention of the code you are writing. Related sections should be grouped together with spacing so someone reading knows what can be moved around and what should stay together. The goal is to make the code as pleasing to someone else’s eye as possible. We all know you are very clever, but a single line that chains together 50 method calls is impossible to decipher. Break it up and I’ll respect you more because you did it for me, not for you.

Everyone has a favorite format. The religious wars about curly braces probably consume half the storage space on slashdot’s servers. I’m not entirely above it – I’m infamous for reformatting code when I take control of it. But if I’m just visiting someone else’s code I have a strict policy that the code I write should be indistinguisable (as much as possible) from theirs. This means formatting it the way they do. Using the same naming conventions. Following their capitalization scheme. The point isn’t to show others how superior my formatting is. It’s to make sure that someone else reading the code doesn’t have an anuerism.

Be Sociable, Share!

2 Comments so far

  1. Gam on March 3rd, 2008

    Never have appreciated a commentary more.

    Sheepishly I need to admit to leaving my muddy work boots on when entering others humble abodes.
    Often, the indecipherable is a clue to the muddled state of the elephant in the china shop. As understanding ensues, so does the softness of our paths through anothers’ well tended garden.

    Sorry for any headaches, thanks for the hospitality of allowing us all access to your code.

    PS I have had to clean my “hacking” so that even I could understand what was going on. It may be a long time before code sings to me, but at least I realize now that it is something from anothers heart.

  2. vdibart on March 3rd, 2008


    I appreciate the comments. I think you perfectly captured the essence of what I was ham-handedly getting at. As you treat your code, so shall your code treat you.


Leave a Reply