The Anatomy of a Coding Guideline

Post from July 18, 2016 (↻ December 5, 2021), filed under Web Development (feed).

Coding guidelines produce consistency, help (code) usability, collaboration, and maintainability, and lead to quality. That is what we all typically learn in development practice, and how I summed it up in The Little Book of HTML/CSS Coding Guidelines (updated).

But what does a guideline consist of? This:

What (not) to do:

We’ve seen with our suspicion whether “do x” already suffices, the key part of a guideline. We cannot do without [defining what to do].

Scope:

Knowing what the guideline applies to is sometimes evident (“sort all CSS declarations alphabetically” already clarifies the scope), sometimes not (“indent by two spaces”—indent what, when, where?). For that uncertainty the scope is generally important, too.

Examples:

Here things get more blurry in that a well-written rule may not need examples; however, in practice we observe that examples do help. Glancing at a rule and an example clarifies and helps colleagues with less experience to get a solid enough idea to know when to apply a rule “when they see it.” Examples may need counter-examples—that is, we should show what is expected and correct according to the rule, and then what would be incorrect.

Implementation help:

Ideally, a coding guideline comes with a tip on how to use it, to make following it easier. For example, “use configuration file x for your editor to enforce indentation,” “include script y to have your code validated,” or “covered by linter.” Although this is a very useful component of a well-written coding guideline, it is often overlooked (even in this booklet).

Explanation:

Although this is not always required, an explanation allows us to help our colleagues understand what the context and purpose is, and facilitate improving or vetoing the rule in question. In a very authoritative setting, explanations may not be as welcome, but in a cooperative one, they are. As domain experts, we should be able to explain why we do what we do, as with imposing guidelines.

What else:

Finally, a complete coding guideline should include an appropriate level of detail. I’d like to keep with the idea of the ideal ID or class name—as long as necessary and as short as possible. Bearing this in mind, when working on a coding standard, it’s better to err on the side of adding [more] detail so that the team can understand the guideline and its rationale.

This comes straight out of The Little Book of HTML/CSS Coding Guidelines, and if you wish to dig deeper, get your own (still free) copy of the book (and check out styleguides.io and cssguidelin.es who like guidelines very much, too).

About Me

I’m Jens, and I’m an engineering lead and author. I’ve worked as a technical lead for Google, I’m close to W3C and WHATWG, and I write and review books for O’Reilly. I love trying things, sometimes including philosophy, art, and adventure. Here on meiert.com I share some of my views and experiences.

If you have a question or suggestion about what I write, please leave a comment (if available) or a message. Thank you!