Monday, April 4, 2016

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.