Jens Oliver Meiert

The Anatomy of a Coding Guideline

Post from July 18, 2016 (↻ July 26, 2017), filed under .

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.

But what does a guideline consist of? This:

The cover of “The Little Book of HTML/CSS Coding Guidelines.”

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 style guides just as much as I do).

About the Author

Jens Oliver Meiert, photo of July 27, 2015.

Jens Oliver Meiert is a developer (O’Reilly, W3C, ex-Google) and philosopher. He experiments with art and adventure. Here on meiert.com he shares and generalizes and exaggerates some of his thoughts and experiences.

There’s more Jens in the archives and at Amazon. If you have any questions or concerns (or recommendations) about what he writes, leave a comment or a message.

Read More

Have a look at the most popular posts, possibly including:

Or maybe say hi on Twitter, Google+, or LinkedIn?

Looking for a way to comment? Comments have been disabled, unfortunately.

Flattr? Found a mistake? Email me, jens@meiert.com.

You are here: HomeArchive2016 → The Anatomy of a Coding Guideline

Last update: July 26, 2017

“If there is any secret, it is missed by seeking.”