Couple of days ago I was pair-programming with a friend of mine, and at some point we had to look at a particularly challenging, objectively horrendous piece of algorithmic code. Of course, we immediately started ranting: mathematicians should never write code; it looks like a piece of crap, with bad parameter names and no documentation; how can anybody have 2300-line C-code in a single file, and so forth. After the venting, my friend turned to me and asked me an interesting question, it went something like:
Him: “Say, how long have you been writing software?”
Me: “Professionally? I don’t know, something like 8 years?
Him: “And this whole time, have you ever seen a code written that somebody else, and said ‘This here is a beautiful piece of code’?”
I answered that maybe once or twice in my life, and maybe that’s once or twice more than a lot of people. And it’s true. You know it’s true. Pretty much every single time you look at somebody else’s code you’ll go “tzzzk” and point out exactly what’s wrong with it. Sure, it might not be that bad that it needs fixing. But still, I’m pretty sure it’s a very rare event that you checked out a piece of code and thought it was really good. This effect doubles and triples when the code gets stale, to the point where I seriously have to see one instance where one person looks at a five year-old code and thinks it’s any good by any standard.
Thing is, every time a piece of code gets written, there are trade-offs that will be made. Simplicity vs (sometimes speculative) Generality, Design vs Efficiency, you name it. If you and the author are on the opposite sides of a trade-off, you’ll just think that the author was just too dumb to notice what you are noticing. On top of this, there’s the style issue. His screen is 120-characters long, yours is 80 – he’s a dumbass for not breaking his code lines. The other way around, he’s a pretentious douche for going with the strict standard, doesn’t he know we all have 23″ screens already? And oh my God, is it seriously still compiled with JDK 1.3? How dare he not to keep up with the times?!
Honestly, it’s a grim fucking revelation. If you’re a coder who likes what he does, you probably take a minute or two to marvel your creation before pushing it in the repository. You probably thought over carefully all the trade-offs therein, and decided one side for a reason, and to you it is just the way it should be (I dare not say perfect). It’s really sad (about as sad that a coding situation can be) that only you see it that way and that every other person will see something wrong in it, and your successor will curse you no matter how hard you tried to be kind to him via your code.
So here are a few tips on how to deal with the situation.
Tip #1: If at all possible, don’t write code
Yechiel Kimchi, my C++ professor in my freshman year in the Technion, used to say that “2 < 1 < 0″. 2 < 1 means that it’s better to write code once than twice, that’s the plain old DRY (Don’t Repeat Yourself) we know. 1 < 0 means, it’s better not to write the code to begin with, if at all possible. Next time you’re sitting down to write that piece of code, think! Am I really the first person in the world who tried to solve this problem? Can I use the language API better to reduce the code here? Is there an open-source project that does what I’m trying to do here? Does a similar code exist somewhere in our project, or another project in the organization, and can be extracted to a common toolkit? If you don’t write code, or you write little code, you’re sure that nobody will “suffer” from your code.
Tip #2: Define and stick to conventions
A lot of times what will annoy people will be the simple conventions. 80-wide lines or 100? Break before curly brackets? Break before “else”? Plain tabs or four spaces? Are wild imports OK or not? Spaces before and after binary operators? White lines between groups of imports? Frankly, it doesn’t matter what you decide, but decide; whether in the organizational level, section level, or project level. The style changes in the code usually cause uber-commits in the source-control, and there’s nothing more annoying to see these done back-and-forth.
Tip #3: Code review and/or pair up!
Unless you’ve been living under a rock, you’ve probably heard of the wonderful Code Review and Pair Programming techniques. These are really, really the basics and are mandatory in any established place. Don’t treat them as a duty, really seize the opportunity to be reviewed. I won’t get into the details on how you should do Code Reviews because (1) that would be long and (2) I don’t think I received enough Code Reviews myself in my career to sound an opinion (I lament that). In any case, Code Reviews take the first layer of crap off, because it ensures that somebody who is not the author (and has bias towards his “baby”) sees the code. The next time someone looks at the code, then, he’s less likely to find stuff that are obviously annoying.
Tip #4: Document your thought-process
Make sure that the non-trivial design choices are documented somewhere. If you’re adding a functionality that might look weird due to a request, add a proper link in the changeset and refer to that request in your Issue Management tool. Be explicit about your choices, be explicit about the options you considered and didn’t take. It’ll be worth its weight in gold (particularly because flip-flops don’t have significant weight) when the next guy tries to figure out why the hell you made the choices that you did.
Tip #5: Two-ways tolerance
When you see someone’s code, don’t be tempted to change stuff on every whim you have. Respect the author, think and try to figure out what went through his mind when he coded it that way. On the other hand accept that your code isn’t perfect, and your trade-offs will be challenged at some point through the life-cycle of the code. This doesn’t mean that you shouldn’t put in all the efforts when checking in your next piece of code. It’s like your child, you do your best to raise it best, but some imperfections will be. And if you don’t believe that I seriously compared treatment of kids to treatment of code, check out the names of my future children.
