Different projects have different coding standards, and some have none at all. How does it affect the quality of code and developers' well-being? What results can we reasonably expect from a style guide?
Let's have a look at the effect of style guides in the real world. Here's how Jerusalem looks like:
These similarly looking buildings are near the city center. Here's a shot of the suburbs:
Same stuff, pretty much. White buildings, red roof tiles – or plain flat roofs.
And now for something completely different:
This is Tel Aviv. Buildings don't look similar to each other here. Nor do different parts of the city:
As you can see, in Tel Aviv, there's no style guide – everyone builds stuff to suit their own taste.
In Jerusalem, on the other hand, buildings have to be covered with Jerusalem stone, giving them their trademark off-white color. Jerusalem owes its visual consistency to a century-old style guide enforced by municipal laws.
Here are a few observations – relevant to most style guides, I think:
- Consistent style is either enforced or lacking. Whatever virtues freedom may have, consistency of style is not one of them.
- Consistent style is functionally inconsequential. Buildings in Jerusalem are about as safe and comfortable as buildings in Tel Aviv.
- Psychologically, style does matter. Many people hate visiting Tel Aviv because it's ugly.
- Whether consistent style is more beautiful is debatable. Many other people hate visiting Jerusalem because it's ugly.
- People will defeat stylistic consistency despite the style guide. Here's an example from one of Jerusalem's suburbs, Ramot Polin – "a housing project for honeybees":
This is consistent with the style guide, but not very consistent with the actual look of other buildings – nor does it look very comfortable. Leading to my last observation:
- A common style can be codified and enforced, but common sense can't be. Municipal law mentioned "off-white", but who would have thought to mention "rectangular"?
A sensible style guide is your one and only way to achieve consistent style – and not much else.
What if a style guide is not sensible? Here's a building from Tirana, Albania:
Here's another one:
Yep, that's the style guide over there – bright colors over ugly buildings. And there's nowhere to hide from the consistent style.
Maybe you actually love this style, and hate Jerusalem's uniform off-white. My point is that either way, the consistent style of one of those cities leaves no place for you to like.
Tel Aviv, on the other hand, has a place to like for both Tirana lovers and Jerusalem lovers. Off-white houses with red rooftops? Neve Tzedek has what you want:
Buildings painted in primary colors? Here's a hotel for you:
Personally, I still prefer Jerusalem though. Consistent style is better – if you like that particular style.
Requiring limestone vs banning asbestos
Can coding standards be described as style guides, or are they more than that?
The Google C++ Style Guide suggests that it is in fact more than a style guide:
The term Style is a bit of a misnomer, since these conventions cover far more than just source file formatting.
The document goes on to say that, apart from "enforcing consistency", it also "constrains, or even bans, use of certain features" – "to avoid the various common errors and problems that these features can cause".
"Enforcing consistency" does sound similar to requiring limestone – there's no direct functional impact. But "banning features to avoid problems" sounds more like banning asbestos – very much because of its functional impact, which can include cancer.
However, language features are different from building materials. Asbestos was discovered, not designed, and they couldn't know it'd cause cancer. C++ RTTI was designed and approved as a standard by strong programmers, who had in mind some cases where they thought it'd be useful.
RTTI is banned by the Google Style Guide, not the way asbestos is banned by regulations, but the way some sculptors prohibit their students to use fingers when they shape the fine details of clay. Learn to use proper sculpting tools – then do use fingers if necessary:
A query of type during run-time typically means a design problem. …you may use RTTI. But think twice about it. :-) Then think twice again.
Think four times and you'll be allowed to use RTTI. Think 1024 times and you're still not allowed to use asbestos in a housing project. That's because construction standards include functional considerations, but coding standards ultimately discuss style and style alone.
That's why the strictest coding standards allow exceptions. And that's why every banned feature is sometimes better than the proposed alternative.
Readability through inconsistency
Style guides enforce consistency. In the real world, we've seen that consistent style matters psychologically. In programming, people also advocate consistency for psychological reasons:
It is very important that any programmer be able to look at another's code and quickly understand it. Creating common, required idioms and patterns makes code much easier to understand.
Psychological reasons are important – but there are symmetric psychological arguments for inconsistency.
For example, required idioms can in fact make code easier to understand – or harder. Let's look at idioms actually required in some style guides:
- The use of C++ "algorithms" such as std::for_each and std::transform instead of decade-old "patterns" called loops. I expect the idea to become widespread again, together with C++11 lambdas. Here's TheRegister's take on the impact on readability.
- Yoda conditions: if(5 == num). This page – first Google hit for "Yoda conditions" at the time of writing – lists only benefits and no drawbacks, and proposes to add this to your style guide. Will code become more readable though? They're Yoda conditions! "If num is five" is how you always say it in English (and Hebrew, and Russian). If five is num, read as natural your code will not.
Of course my opinion on the readability of these patterns is debatable – which is precisely my point. Once a style guide is chosen, some people will experience the joy of fluent reading every time they hit if(5==num). Others will experience the pain of a mental roadblock – also every time.
A style guide will have something to dislike for everyone. When tastes are sufficiently different, the average amount of cringes per person stays the same under consistent style – and the variance rises (someone will hate a particularly popular mandatory pattern).
It's like keeping wealth constant and increasing inequality – something not even a political party would advocate. How is this psychologically a win?
But let's go ahead and assume that the "required idioms" suit everyone's taste, and, by themselves, actually make code easier to understand. Still:
- External libraries will not follow your style guide. They follow style guides of their own. And this inconsistency can improve readability. Code using the library stands out, and the library's style can match the accepted domain-specific conventions better than your local style. In computer vision, X is the real world coordinate, x is the pixel coordinate – contrary to many software style guides.
- You can't count on stylistic conventions, because there are exceptions. Google's code orders parameters such that inputs come first, but memcpy & snprintf don't. You either have to look out for exceptions or risk misunderstandings by blindly assuming consistency.
- Different people think differently, even if their code looks the same. I find it easier to understand programmers' intents through their unique style. When they're all forced to write superficially similarly, I can't tell who wrote what, and what the subtext of the code is.
I'll illustrate the last point with a couple of examples. I knew O.M. before I ever saw him and before I even knew his name. To me, he was the programmer with the two spaces before the trailing const:
inline int x() const;
I knew him through his code: mathematically elegant, obsessive about fine details of type-based binding and modeling. I could guess what he left out with an intent to maybe add it later. I understood him.
Likewise, I can always spot G.D.'s code by the right-leaning asterisk:
G.D. certainly couldn't care less about types – similarly to most people with this asterisk alignment. I know his code: terse, efficient, to the point. I know what to expect.
Who wrote this code?
camelCaseName = longerCamelCaseName-camelCaseName;
I dunno, the collective unconscious wrote it. Anyone could write it – or several people patching after each other. I fail to identify with the author and guess his intent – it could be anyone. The code has no smell or taste to me.
This can sound a bit crazy – "does he actually advocate that everyone develops as uncommon style as possible as a way to mark his trail"? Of course I don't mean that.
I think what I'm saying can make more sense if you think of style and taste in code as analogous to the taste of food. Of course it's ridiculous to expect every restaurant to make food with a unique taste. Many people like pizza, many people know how to make pizza – so expect much similarly-tasting pizza around.
But we wouldn't like to always eat food cooked to the same spec by restaurants in a single franchise. If someone knows to make food with a unique taste, we welcome it.
And unique taste of your food doesn't indicate that it's bad for your health. Moreover, food with a familiar taste can be very unhealthy – much of it is. Code in a familiar style has a comforting look – sometimes misleadingly.
I don't think requiring the same taste everywhere is how you improve the health of a code base.
I'm naturally inclined to argue against coding standards, because it feels like bureaucracy unthinkingly imposed on the work process from above. However, what if it's not imposed from above – what if the programmers themselves want it?
Many certainly do. Many good ones do.
Incidentally, while I was writing this, I stumbled upon an article arguing for consistency – for the very reasons I use to argue against it:
If code isn’t written in a consistent style in your team, whenever you come across code with the spacing a bit wrong, the first thing your head’s going to process is "I didn’t write this."
…Exactly why I like personal style! I really didn't write it – it's his code, I want to understand him, and his style helps greatly.
This is a natural feeling, and as we all know coders have a hard [time] to restrain impulse to rewrite any piece of code they didn’t write.
I understand that impulse very well. Personally, I hate new food more than anyone I know – I eat the same thing every day, for months, for years. I do prefer Jerusalem to Tel Aviv. And I like consistent style – especially my own.
But why should others be forced-fed my favorite cabbage salad? Is consistency that much prettier than freedom?
I don't argue with people who favor a consistent style – and I can't. The article above is nostalgic about a team that followed a style guide "religiously". How can nostalgia be refuted? Clearly, consistent style can create a unique team spirit that to some is valuable and memorable.
All I can and do argue is that a lack of a style guide can also create a good atmosphere that is preferred by some other people.
In fact I believe it is exactly team spirit that a style guide – or lack thereof – actually affects. All other effects come indirectly through the impact on atmosphere. Here's my attempt at taking the social effect into account:
- I won't break established conventions. Following conventions is a great way to say, "I respect the local tradition and the wisdom it embodies." And I'll thoroughly enjoy the limestone covering our code – I like consistency. Yay, a beautiful code base! And if the convention is really bad – I hopefully won't need to join the team in the first place.
- However, I won't establish and enforce conventions when I'm the one starting with a clean slate. Having no conventions is a great way to say, "join my project to express yourself without artificial constraints".
From team spirit to grassroots bureaucracy
Did you know Ken Thompson is not allowed to check in code at Google? He said so in his Coders at Work interview:
Seibel: I know Google has a policy where every new employee has to get checked out on languages before they're allowed to check code in. Which means you had to get checked out on C.
Thompson: Yeah, I haven't been.
Seibel: You haven't been! You're not allowed to check in code?
Thompson: I'm not allowed to check in code, no.
The programmer who co-created Unix is not allowed to check in code. If this isn't a bureaucracy, what is? But it's inevitable – with rules, you always paint yourself into a corner that way. Allow some to break the conventions, and you will have offended everyone else. Use the same rules for everyone – and some won't contribute.
Of course, Thompson does contribute to Google. Well, Google has plenty of ways to motivate him to do that. And, apparently, they have good programmers willing to write production code based on his uncommitted prototype code.
But we're not all like Google that way. We can't all afford the inevitable laughable outcomes of bureaucracies. If you come across an original programmer with an off-beat style, do you want him to join your project or to move on?
Grassroots bureaucracy is still bureaucracy. I wouldn't object to an established bureaucracy that people claim to value. But I wouldn't establish a new one, either.
A style guide can make code look prettier to some – and uglier to others – but not tangibly better, except if programmers enjoy it so much as to produce better code.
This is equally true for the lack of a style guide. The results of freedom look prettier to some and uglier to others.
Personally, I believe that one rule too few is better than one rule too many, so I don't bother to enforce a common style.
P.S.: when I become a neat-freak
Generally, I tend to enforce little to no conventions. Here are the exceptional situations where I actually enter the ridiculous position of telling people how to write their code.
Interfaces should be consistent
I don't care if an interface looksLikeThis or like_this. But if it uses both, then I'll ask the author to change it to one of the styles – the one which came first. For users to feel confident, an interface should look well thought-out – which implies an illusion of a single author, which implies a consistent style.
By "interface", I only mean the outermost stuff called by module users. Internal functions, classes, etc. can look like Tel-Aviv as far as I'm concerned. For instance, in a simple server, the "interface" to me is just the protocol, and nothing in the code itself.
Warnings should be errors
I hate the concept of compiler warnings – I link it to the concept of guilt. "Fine, be that way, do this evil implicit conversion thing – but if something happens, I will have told you so." Why should we put up with such manipulative behavior? Pick a position – refuse to compile, or compile silently.
However, in practice, compatibility issues make what has to be errors into warnings. If it compiled 30 years ago, it has to keep compiling, even if nobody wants it to compile in new code. Even if compilers could always prove the code wrong, but initially didn't bother, and it happens to work in old programs.
So, to the dismay of freedom-lovers, I turn warnings into errors where I can (as in -Werror) – even if I can't cherry-pick the "right" warnings. Mainly since when a file generates 10 (false) warnings, the eleventh (truly useful) warning goes unnoticed.
Another reason is that warnings cause guilt – they are evil, and must be destroyed. If I didn't destroy them by turning them into errors, I'd have to destroy them by disabling them. Then I'd never get that eleventh useful warning.
But except for these two pet peeves – interfaces and warnings – I do think grown-up programmers should be left alone.
P.P.S.: Greetings from the Overextended Metaphor Parrot
Originally, I had a few references to Bauhaus architecture in the text – how Tel Aviv has buildings in the Bauhaus style and Jerusalem doesn't because of its limestone requirement, and how Ken Thompson's inability to commit code at Google is analogous to that. However, as a commenter pointed out, there are buildings in the Bauhaus style in Jerusalem – in my own neighborhood, actually, so I obviously walked past them plenty of times.
I guess this goes to show that good architects have no trouble complying with a style guide – and that I shouldn't overextend metaphors in areas where I'm not minimally competent.