The little book of HTML/CSS coding guidelines

Consistency

The major, direct benefit of coding guidelines is improved consistency. Why? Because with comprehensive coding guidelines all code gets formatted the same way. Rules are always indented the same way. Declarations appear in the same order. Element names are always lowercase.

Consider this example:

#intro {
  background: #fff;
  color: #000;
}

.note {
  color: gray;
  background: white
}

Suppose you need to edit this style sheet. How do you specify and order the colors for a new author section? Meet inconsistency.

While one might argue that keeping the guidelines in mind makes the process of writing code itself a little slower, locating and refactoring code becomes much easier and faster.

Usability

An indirect benefit that follows consistency is improved usability. Improved developer usability, that is. Improved “ease of use and learnability of code,” then, as I described in The Little Book of HTML/CSS Frameworks. Why? Because through coding guidelines, developers are able to set and trust expectations, which again helps locating and refactoring code.

Collaboration

More importantly, yet also consequentially, coding guidelines facilitate collaboration. They make it easier for you to understand your colleagues’ code (and vice versa), and to hand over code to someone you haven’t work with previously. They don’t require as much time adjusting to someone else’s coding style, especially not when one follows the otherwise laudable habit of sticking to the code style a given project is using.

Maintainability

Lastly, coding guidelines and the consistency they bring to our code help maintainability. They do so because guidelines constitute a form of organization, a lower degree of entropy, which makes it easier to order, or keep things in order. Although often forgotten, maintainability important, as there’s no code in existence that will only be touched once. Even if it’s not going to be edited or updated again, eventually it must be decommissioned. And that falls under maintenance, too.

Structure

At this point, we should work with a few examples. Let’s look at a few random coding guidelines, without judgment nor endorsement:

Harry Roberts’ CSS Guidelines recommend hyphens:

Hyphen Delimited

All strings in classes are delimited with a hyphen (-), like so:

.page-head {}

.sub-content {}

Camel case and underscores are not used for regular classes; the following are incorrect:

.pageHead {}

.sub_content {}

Dan Hay’s coding standards say the following about “verbose” HTML code:

Don’t use tags that STADN (sit there and do nothing)

STADN tags do just that—they don’t actually contribute much to the content or layout of a page. An example of a STADN tag would be:

<FONT SIZE=2><B>&nbsp;</B></FONT>

The bold and font tags do not contribute to the layout or appearance of the non-breaking space. We could add as many surrounding tags to the non-breaking space and it still wouldn’t affect the appearance of the page.

Most HTML editors liberally insert STADN tags. This behavior is yet another reason why HTML editors must not be used.

(A comment, “tag” should rather say “element” here.)

And for WordPress, vendor-specific extensions are worth special attention:

We use grunt-autoprefixer as a pre-commit tool to easily manage necessary browser prefixes, thus making the majority of this section moot. For those interested in following that output without using Grunt, vendor prefixes should go longest (-webkit-) to shortest (unprefixed). All other spacing remains as per the rest of standards.

.sample-output {
    -webkit-box-shadow: inset 0 0 1px 1px #eee;
    -moz-box-shadow: inset 0 0 1px 1px #eee;
    box-shadow: inset 0 0 1px 1px #eee;
}

(Legal note: This coding guideline has been quoted from the CSS Coding Standards by WordPress, used under GPLv2.)

These guidelines, and guidelines in general, are very differently written, but we find similarities:

• What (not) to do

• Scope

• Examples

• Explanation

These are the main ingredients of a coding guideline.

Let’s have a closer look at this structure:

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 it.

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 enough detail so that the team can understand the guideline and its rationale.

With that, we should have an idea of the minima and maxima of a coding guideline:

Priority

But is the structure all that makes a coding guideline? Let’s consider the ever-popular order to indent by x as well as the ever-beloved idea to use “semantic markup.” What makes them different?

I believe we will soon discern a difference in terms of preference versus quality.

The indentation rule is first and foremost preference, especially when noting that tab characters can be configured to be displayed with n spaces, meaning that every team member could produce code that’s indented the same way while still enjoying their own individual preferences.

The semantic markup rule, however, has a qualitative bearing, for if we understand the use of markup according to its meaning paramount to it being parsed correctly and accessibly, then this rule results in a difference in quality of code, depending on whether and how it’s followed.

For coding guidelines, then, this difference results in a sense of priority. Though preference-based rules are still relevant because they lead to consistency, which in turn gives us all the benefits we discussed earlier (usability, collaboration, maintainability), the quality rules, when sound, make code more consistent and better.

The suspicion grows that preference rules are easier to define and spot than quality rules, but the jury’s still out on that.

Descriptive

The descriptive approach works if the difference between code reality and our goals is minor. Then we can simply outline how things are done now, let the whole mélange sit for a few minutes, and reap the reward when we onboard new team members.

For example, if everyone on the team is validating their HTML code, as it should be done (there’s no need and no excuse for not using HTML correctly), we say:

Release only valid HTML code

Prescriptive

If the reality/goal difference is bigger, we want to take a prescriptive (i.e., normative) approach, meaning to tell what to do:

Release only valid HTML code

But isn’t that the same rule?

It is the same rule on the surface, yet a different one when looking at the context. Whether we describe or prescribe coding standards doesn’t depend on the rule, but on the situation. In both cases, we want to anchor, in writing, what code we expect.

The prescriptive approach, then, depends on enforcement: when everything’s good already and we only describe, there’s little need to enforce.

Once there’s something to prescribe, there’s also something to enforce. We’ll look at this Coding Guidelines in Practice.

Mixed

Yet then, in everyday coding life, we face coding practices we want to document (describe), and others we want to achieve (prescribe). This means that most coding guidelines and standards include rules that are mixed, using both approaches.

Decision Process

How do we decide when to use which coding guidelines? The flowchart in Figure 1-1 can help us:

What we can see is that for a team of one, we don’t strictly need coding guidelines. It is recommended, however, to look into using coding guidelines even in this case—perhaps making use of public ones, such as the Google HTML/CSS Style Guide with the exception of two-space indentation (even after leaving Google, I still follow these guidelines for my personal projects).  

Whenever two or more people work together, however, coding guidelines become useful, and really important. And there the question is one of goals, and existing quality, to say whether we need a descriptive or prescriptive approach, considered for each guideline.

Communication

The larger the organization we’re working in, the more important is the point of communicating our guidelines: Everyone writing code should know about them.

Fortunately, in most modern companies, teams have mailing lists to communicate guidelines to. It makes sense to share updates the same way, or to add all relevant people to a special mailing list related to coding style.

Compliance

The next important aspect is achieving compliance—that is, enforcing the guidelines. This is normally a two-fold process.

First, we need to measure whether coding guidelines are followed or not. For that, we need to set up the necessary infrastructure and tools, though manually probing for compliance, as with code reviews, does work, too. In practice, this piece is neglected rather frequently, and organizations don’t know much about their actual compliance rates. Automation, which we will look at momentarily, is crucial here. How to automate the whole compliance part is not subject of this booklet, however.

Second, we need to enforce the code style we want to see. Here, too, automation is desirable, but we also need a way to track and score offenders. Tying coding style compliance to performance metrics that got communicated in advance is an effective approach. For example, a team member who repeatedly violates coding standards could get a lower performance rating than one who does keep with it.

Reviews

Our coding guidelines should not be considered a one-off effort. Just as we must maintain our code, so too should our guidelines be reviewed from time to time—it’s important to update the documentation to reflect changes to guidelines as they arise.

It is something that gets maintained (as much as the affected code—we should not forget to update it when guidelines change). It is therefore recommended to not only assign a primary contact (or perhaps a small team of experienced volunteers) to be guideline owners, but to also schedule at least quarterly reviews that check whether updates are needed.

Automation

Lastly, a particularly useful habit—and a key for future handling of coding guidelines—is automation. The assessment of code quality should be automated as much as possible and we should also automate improving and fixing code.

At the moment, there is no single out-of-the-box solution for this (only small scripts abound), but our vision overall should be that our development environment shows us local coding preferences, highlights violations and fixes them for us; that then, when we stage our code, additional checks are run that likewise report issues and fix them, and that at the end, optimized, minified, compressed, our code goes live in the shape we had envisioned it.

General

<script src="//www.google.com/js/gweb/analytics/
autotrack.js"></script>

<ul>
    <li>HTML
    <li>CSS
</ul>

color: #cc0078;

<A HREF="/">Home</A>

<p>What?_

<!-- TODO(john.doe): revisit centering -->
<center>Test</center>

HTML

<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>

<img src="muscles.jpg" alt="Medical illustration of the muscles in the leg.">

<p>The currency symbol for the Euro is "€".

<!DOCTYPE html>
<title>Saving Space</title>
<p>Qed.

<link rel="stylesheet" href="//example.com/default.css">

<table>
    <thead>
          <tr>
               <th scope="col">Income
               <th scope="col">Taxes
    <tbody>
          <tr>
               <td>$ 5.00
               <td>$ 4.50
</table>

<a class="action promo">Sign in</a>

CSS

/* Meaningless */
#yee-1901 {}

/* Presentational */
.button-green {}
.clear {}

/* Specific */
#login {}
.video {}

/* Generic */
.aux {}
.alt {}

#navigation {}
.atr {}

#nav {}
.author {}

.foo-help {}
#bar-note {}

border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%;
line-height: 1.6;
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;

border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;

margin: 0;
padding: 0;

font-size: .8em;

color: #ebc;

.demoimage {}

.ad-sample {}

background: fuchsia;
border: 1px solid;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
border-radius: 4px;
color: black;
text-align: center;
text-indent: 2em;

@media screen, projection {

    html {
          background: #fff;
          color: #444;
    }

}

.test {
    display: block;
    height: 100px
}

.test {
    display: block;
    height: 100px;
}

h3 {
    font-weight:bold;
}

h3 {
    font-weight: bold;
}

#video{
    margin-top: 1em;
}

#video
{
    margin-top: 1em;
}

#video {
    margin-top: 1em;
}

h1,
h2,
h3 {
    font-weight: normal;
    line-height: 1.2;
}

html {
    background: #fff;
}

body {
    margin: auto;
    width: 50%;
}

@import url(//example.com/default.css);

html {
    font-family: 'helvetica neue', helvetica, sans-serif;
}

Summary

This has been a little, rather tiny, treatise on coding guidelines. Although short, it covered several key ideas:

Coding guidelines govern how we write code.

Coding guidelines directly help consistency, and through that, indirectly, impact usability, collaboration, and maintainability.

Coding guidelines are important.

The main ingredients of a coding guideline are: what (not) to do within a particular scope, examples, and an explanation.

Coding guidelines can deal with preference or with quality.

Coding guidelines can be descriptive, prescriptive, or both.

Coding guidelines must be communicated, enforced and reviewed.

And, there are some solid coding guidelines out there.

At Google we used to say, “the point of having style guidelines is to have a common vocabulary so people can concentrate on what you’re saying rather than on how you’re saying it.” I hope that despite the brevity of this pamphlet, you, too, can now help your team concentrate on what you’re saying, a little better.