Stuff Everyone Should Do (part 2): Coding Standards

Stuff Everyone Should Do (part 2): Coding Standards

Jul 14 2011 Published by MarkCC under Programming

Another thing that we did at Google that I thought was surprisingly effective and useful was strict coding standards.

Before my time at Google, I was sure that coding standards were pointless. I had absolutely no doubt that they were the kind of thing that petty bureaucrats waste time writing and then use to hassle people who are actually productive.

I was seriously wrong.

At Google, I could look at any piece of code, anywhere in Google’s codebase, and I could read it. The fact that I was allowed to do that was pretty unusual in itself. But what was surprising to me was just how much the standardization of style - indents, names, file structures, and comment conventions - made it dramatically easier to look at a piece of unfamiliar code and understand it. This is still surprising to me - because those are all trivial things. They shouldn’t*have much impact - but they *do. It’s absolutely shocking to realize how much of the time you spend reading code is just looking for the basic syntactic structure!

There’s a suite of common objections to this, all of which I used to believe.

• It wastes time!

  I’m a good coder, and I don’t want to waste time on stupidity. I’m good enough that when I write code, it’s clear and easy to understand. Why should I waste my time on some stupid standard? The answer is: because there is a value in uniformity. As I alluded to earlier - the fact that every piece of code that you look at – whether it was written by you, by one of your closest coworkers, or by someone 11 timezones away – will always demarcate structures in the same way, will always use the same naming conventions - it really, genuinely makes a big difference. You need so much less effort to read code that you haven’t looked at in a while (or at all), because you can immediately recognize the structure.

• I’m an artist!

  This is phrased facetiously, but it does reflect a common complaint. We programmers have a lot of pride in our personal style. The code that I write really does reflect something about me and how my mind works. It’s a reflection of my skill and my creativity. If I’m forced into some stupid standard, it seems like it’s stifling my creativity. The thing is, the important parts of your style, the important reflections of your mind and your creativity aren’t in trivial syntactic things. (If it is, then you’re a pretty crappy programmer.) The standard actually makes it easier for other people to see your creativity - because they can actually see what you’re doing, without being distracted by the unfamiliar syntactic quirks.

• One size fits all actually fits none!

  If you have a coding standard that wasn’t designed specifically for your project, then it’s probably non-optimal for your project. That’s fine. Again, it’s just syntax: non-optimal doesn’t mean bad. The fact that it’s not ideal for your project doesn’t mean that it’s not worth doing. Yeah, sure, it does*reduce the magnitude of the benefit for your project, but at the same time, it *increases the magnitude of the benefit for the larger organization. In addition, it frequently makes sense to have project-specific code styles. There’s nothing wrong with having a project-specific coding standard. In fact, in my experience, the best thing is to have a very general coding standard for the larger organization, and then project-specific extensions of that for the project-specific idioms and structures.

• I’m too good for that!

  This is actually the most common objection. It’s sort-of a combination of the others, but it gets at an underlying attitude in a direct way. This is the belief on the part of the complainer that they’re a better programmer than whoever wrote the standard, and lowering themselves to following the standard written by the inferior author will reduce the quality of the code. This is, to put it mildly, bullshit. It’s pure arrogance, and it’s ridiculous. The fact of the matter is that no one is so good that any change to their coding style will damage the code. If you can’t write good code to any reasonable coding standard, you’re a crappy programmer.

When you’re coding against a standard, there are inevitably going to be places where you disagree with the standard. There will be places where your personal style is better than the standard. But that doesn’t matter. There will, probably, also be places where the standard is better than your style. But that doesn’t matter easier. As long as the standard isn’t totally ridiculous, the comprehension benefits are significant enough to more than compensate for that.

But what if the coding standard is totally ridiculous?

Well, then, it’s rough to be you: you’re screwed. But that’s not really because of the ridiculous coding standard. It’s because you’re working for idiots. Screwing up a coding standard enough to really prevent good programmers from writing good code is hard. It requires a sort of dedicated, hard-headed stupidity. If you’re working for people who are such idiots that they’d impose a broken coding standard, then they’re going to do plenty of other stupid stuff, too. If you’re working for idiots, you’re pretty much screwed no matter what you do, coding standard or no. (And I don’t mean to suggest that software businesses run by idiots are rare; it’s an unfortunate fact, but there’s no shortage of idiots, and there are plenty of them that have their own businesses.)