Style guide style guide

After looking over Google's style guide for shell scripting, I feel like I need to write up what should be obvious: the style guide for style guides. It's a common failing of coder culture that we think it's best to try to write style guide documentation as if it were code, being as explicit as possible and catching exceptional conditions where possible.

Unfortunately, the audience is not a computer, it's a programmer, and programmers do many things that computers don't:

• Ignore large sections of prose
• Discard the parts they disagree with
• Become defensive

So, to avoid these problems, here are some simple guidelines along with examples from the Google document.

Keep it short

Don't include anything that you would expect most code reviews to catch.

Here's what the Google style guide had to say on line length:

Maximum line length is 80 characters.

Generally speaking programmers are familiar with the need to limit line length, and if they're not, they will be after their first code review. This is an unnecessary element of a style guide that will probably result in many people just giving up reading it.

Don't include links unless you're sure

The Google style guide contains a link to the C++ style guide. That seems reasonable. The problem is that the link is dead. There's nothing that makes your document seem obsolete and unmaintained faster than a dead-link. If you're going to include a link, figure out how you're going to maintain it when it changes and how you will detect that. Links are effectively code, and your code should be tested.

Dictate the goal, not the method

For example, the style guide in question describes indentation:

Use blank lines between blocks to improve readability. Indentation is two spaces. Whatever you do, don't use tabs. For existing files, stay faithful to the existing indentation.

It's clear from context that what they were trying to do was to get programmers to use a common convention and not break others' editors with context-sensitive tabs. That could just as easily have been stated as, "Don't use raw tab characters and generally indent to maintain consistency with existing code bases." Mandating two spaces isn't necessary if that's the local convention already and if it's not, then the style guide isn't going to change that.

Don't mandate aesthetics

As with whitespace, coding style guides for businesses shouldn't be telling people what kind of code they should consider beautiful. Here's an example:

Put ; do and ; then on the same line as the while, for or if

This too could simply have been a call for consistency: "Format do/then block constructs consistently with existing code." But instead, the author of this guide is trying to make sure that code that they have to look at will be pleasing to their eyes.

Consider cost

Consider that the amount of time consumed reading your style guide will probably cost more than the money it will take to pay you to write it. Every time you inject something into it, you're spending money twice. That money should have some return.

Separate "best practice" from "known pitfalls"

All too often, style guides suggest something for opaque reasons. In many cases, the reason for a rule is vastly more important than the rule. For example, the Google style guide actually does explain its reasons when it suggests the use of "[[..]]" over "[...]":

[[ ... ]] is preferred over [, test and /usr/bin/[.
[[ ... ]] reduces errors as no pathname expansion or word splitting takes place

Users of the style guide are warned in this way that when they see uses of "[...]", they should be aware of the potential bugs that might have been introduced!