I was never a boyscout. I never got badges, or went hiking, or helped old ladies across the street. I was infrequently prepared (let's just call that late binding, k?). But one thing that I always admired about those kerchief-toting, three-finger-saluting momma's boys, was their oath:
On my honour I promise that---
1. I will do my duty to God and the King.
2. I will do my best to help others, whatever it costs me.
3. I know the scout law, and will obey it.
Aside from the fact that this little ditty smells like a nasty case of infinite tail recursion, how do these three steps relate to developers? As the inimitable Dr. House says, "here, please hold my metaphor."
First, we have a duty to our users. Ipso Facto, Quod Erat Demonstrandum, Ad Hominem. When it comes to the code we write, our users serve as God and King. Every poorly scoped data structure, every unfortunate inheritance chain, it's all for the user. If it's not, you tempt a fate I wish upon no man: irrelevance.
This duty requires that our code be useful. That it serve some end in making a feature, and finally a product, that our users want to use. This is not a binary choice we have to make--each module or feature lies somewhere on a continuum of uselessness. And let's face it, I'm talking mainly to nerds. We love challenges and ownership, and all too often we love them to the point that our exuberance overshadows the most important factor in our decision to write that next line of code.
Second, fellow scouts, and this rule follows from the first, we must write our code to be pleasing to our compatriots. We're all working together to achieve #1. To do that as efficiently as possible, we must set aside our stunning individuality and write code that makes sense for others to read and manipulate. Why? This is simple. This is the power of a team. This is why organizations are formed. Because together, we can be something greater than we can individually.
This is not to say that you should double check every API call you make with each of your team members before you make it. Or even that you should spend twice as long writing documentation as you have written code, that will coincidentally never be read. Rather, you should:
- Balance terseness with comprehensibility.
- Write with refactoring in mind.
- Minimize namespace clutter. If your language allows you to code descriptively, then for god's sake, do it.
- Be careful about scope. The localer, the better. Tighten that contract up and make refactoring exponentially easier.
- Just-in-time abstraction. Don't create one unless you need to, but as soon as you need to, do.
- Don't hide shortcomings. Getting creative with whitespace and extra long lines of code is deceptive. If you find yourself wanting to do this, it's usually time for a better abstraction.
- Self deprecating comments don't make up for incorrect code. Your fellow developers understand there are always ways to make things better. Get it to the point where you don't need to mention the magnitude of the approaching hack, before you commit.
Of course there are *always* exceptions to the rule, and you're called upon to make those judgment calls time and time again. But you'll do fine if you remember the first two Code Scout rules:
- I will do my duty to the users.
- I will do my best to make my code a living document for multiple authors, no matter what it costs me.
- return arguments.callee.apply(this, arguments);
And the final Code Scout rule: