JavaScript style and the art of anal retention

Brian Dillard, Wednesday, September 26, 2007 @ 8:01 am

Years ago, in a former life, I was not just a journalist, but the worst kind of journalist: a copy-editor. I was paid to rewrite other people's copy, often while they were sitting next to me, so that it conformed to a set of stylistic conventions. Copy had to follow, in descending order of importance, the stylebook of whatever publication I actually worked for, the Associated Press stylebook, and standard grammatical rules.

The theory behind copy-editing is that convention is good even when it's arbitrary: "gray" rather than "grey" even though both spellings are listed in the dictionary. The more consistently a given publication handles specific ambiguous cases, the easier that publication is to read - or so the theory goes. ***

Software development, especially in a large, shared codebase, can work a lot like a newsroom: Project leads function like desk editors, technical leads like copy editors, code reviews like editing sessions, and releases like print runs. The big difference with code is that it will get rewritten repeatedly even after it's "gone to press."

When I sit down to extend other people's code, I find it difficult to dive in until I've cleaned things up a bit. I don't fix bugs. I simply reformat the code so it looks more like my own. With JavaScript, I move braces around, tweak the commenting style, rewrite certain if-then-else statements using the ternary operator, and so on. Ideally, none of this affects the functioning of the code. It simply makes the code easier for me to read, understand and extend. It puts it into my vernacular.

None of that would matter if I didn't have to check the edited code back in after I was done. Once somebody notices that you've altered non-functional attributes of their code, they can get a little peeved. Back in my Orbitz days, we tried to cut off any discussion about such issues by intoning, "Tabs vs. spaces! Let's move on!" Indention style is the most basic code-style decision, but it's practically a religious issue. There's no way of proving that your side is right. It's a matter of faith, so why waste time arguing? The same goes for most other arbitrary stylistic tics. IDEs, with their auto-format options, help ease this kind of conflict. But if you're an adherent of, say, Hungarian notation, you're still going to get caught up in some pretty endless debates.

When it comes to JavaScript, some stylistic tics aren't so arbitrary. Subtle changes in our coding style can improve not just readability, but also shelf life, cross-browser compatibility, and ease of minification. Several brand-name JavaScript authors and projects have weighed in with style guides. Some follow the AP stylebook model: seemingly arbitrary commandments. Douglas Crockford provides more context than most with his Strunk & White-inspired "Elements of JavaScript Style" (in two parts: 1 and 2). But the Mozilla and Dojo folks certainly have a lot of good advice.

Are all of you JavaScript authors aware of these resources? If so, which do you find most useful? Which are worth following slavishly? Which need to be ignored? Personally, I find all of these examples useful because they force me to think about my own coding conventions - many of which I picked up unconsciously - and decide which ones actually add value rather than simply manifesting my anal-retentiveness. Understanding these guidelines is like studying the source code of third-party libraries. It helps you see how other people are solving the same problems you're facing.

Here are the links:

• Dojo style guide
• Ajaxian commentary on Dojo style guide
• Crockford style guide, part 1
• Crockford style guide, part 2
• Ajaxian commentary on Crockford style guide
• Mozilla style guide

*** Incidentally, that's why most newspaper journalism does so many
weird things consistently, such as putting all modifiers before all
helper verbs. The phrase "already had been working" may be harder to
read than "had already been working," but it's easier to codify in
absolutes. What was that about "the hobgoblin of little minds"?

agile ajax

Comments: 3 so far

• Leave a comment
• Comment feed for this post
• TrackBack URL

1. 

   I couldn’t agree with this more. Especially the part about checking the code in after spending hours cleaning up poor indentation or poor naming.

   I think that poor style in code creates poor code, though.

   Comment by Anonymous, Thursday, September 27, 2007 @ 7:20 am

2. 

   The problem is, like with writing, everyone has their own style that works for them. Unlike in the press industry, the development community, especially in web development, is very diverse. Some companies may have guidelines that are almost opposite to that of another company, while most have little or no guidelines. I’m very anal about proper spacing and format, as it makes it much easeir for me to read and debug. However when I get into the bulk of coding writing, commenting goes by the wayside all together, and I have to almost always go back through and add short comments, something which I always get chastised about. I think people should allow coders to write in the way that works best for them, while following some minor guidelines that make it universally readable. No one likes standards forced upon them. If anything, the biggest push for some sort of standard should be focused on naming conventions, as nothing is worse than having near identical variable names (firstDay, fDay, day1, etc) repeated throughout scripts.

   Comment by T.J., Thursday, September 27, 2007 @ 9:24 am

3. 

   Any coder worth is pay can pick up and run with any given style, no matter how silly or pedantic that style is. In the open source projects i run, i never place any restrictions on style. Not only do my style preferences change over time, but i find it rude to impose a style on someone who is taking time out of their life to contribute to my project. If their style bugs me *that* much then i’ll re-format the code (a couple-keystroke operation in xemacs), but there’s no reason in the world to fuss about coding style.

   If you find yourself fussing about coding style, it’s time to stop, take a breather, and then go find something else to worry about.

   Comment by Stephan Beal, Monday, October 1, 2007 @ 4:34 pm

Leave a comment