Web Coding Style Guides

There is nothing like well written code. I am not talking about the efficient type either. I mean the clean, well-formatted, neat looking code. Code that looks the same no matter what environment it is displayed in. Clean code, both efficient and neat, makes the world go ’round.

However, how do you know what is considered clean code? What is the baseline you are to compare your code to? The answer lie in style guides. Every programming language has them, both for the code you write and the code that powers the language. By reading and following your chosen language’s style guide, you can be sure your code is a piece of code beauty (that does not mean ASCII art either šŸ˜› ). In the world of HTML, CSS, and JavaScript, there is no single style guide to follow but rather many to choose from. Although there are a few predominant ones and they usually contain some of the same suggestions, it is up to you to choose which one to follow. Furthermore, there may be a few rules from one you like from guide X but overall prefer guide Y. You may also have personal preferences not listed. All the decisions can become confusing.

This is where this post comes in. I am going to show off a few of the most well-known style guides and provide some tips on handling it all.

Are you in the reading mode? I hope so, because this quest for cleaner code is going to be long. Forward, march!

Note: this post is not directly about discussing code styles you, I, or the programmer next to you uses. While I will briefly mention some of my coding style, the primary objective of this installment is to explore some of the HTML, CSS, and JavaScript style guides out there and help you develop your own personal guidelines. Discussing personal style guides is beyond the scope of this post. šŸ˜‰ In addition, the words “rules” and “guidelines” and their variations are used synonymously to mean “suggested practice”, per the aforementioned purpose of this document.

Code Guide by @mdo

Mark Otto (better known as @mdo) could be considered an influential GitHubber. Widely known as the creator of the unofficial GitHub Buttons and developer of Bootstrap, he has now come out with Code Guide, an HTML and CSS style and efficiency coding guide. Unlike other guides, Code Guide is not just a style guide: it contains basic yet wise information that (in my perspective) should be present in every single HTML and CSS Fundamentals lesson plan, book, and tutorial. These things, such as 2 space indentation, always using the HTML5 doctype, and neatly spacing your CSS are practically industry standards, and are basic but key principles to clean code. While at times it can be a bit vague, this is a solid guide with basic yet important rules that should be followed. Furthermore, Code Guide is open-source, so you can suggest content to be covered. While others guides are more in-depth and informational, Code Guide is my GOTO guide when questions about HTML and CSS cleanliness standards are posed or even when coding myself.

jQuery Style Guides

While rather brief, the jQuery style guide (primarily the JavaScript section) also stands out for promoting fundamentals to clean code. Topics from multi-line statements to equality to assignments are covered in this guide. I really do not have too much to say here, simply because it is rather short, even though it contains rather rich content.

PEP8 – Python Style Guide

PEP8 is the name of the Python style guide (PEP stands for Python Enhancement Proposal). You are probably wondering

Now why has le717 brought Python into this? How does Python even remotely relate here?

For starters, Python is used in web development as server back ends. šŸ˜› I have introduced PEP8 into this post not because of Python’s role or because I code in it, but because it contains, at least in my perspective, many good points some guides may leave out.

Take, for example, the following lines of Python.

from __future__ import print_function

def sayHi():
    """Calculates if the user should be greeted or not"""
    if 12 + 2 == 14:
        answerOne = true 
        answerOne = false

    if "Oh my, it's a bear" == "There is a lion in the streets!":
        answerTwo = true
        answerTwo = false

    # The user does not get to be greeted because they can add or read too well.
    if (answerOne and not answerTwo):
        print("Hi, user!")

This silly little snippet of code follows the PEP8 guidelines. As you can see, it is very easy to understand, consisting of two if blocks (one evaluates to true and the other false) and displays a message in the console if the conditions are met. But what is it exactly that makes this code so readable? There are a few things in play here, but the one I want to point out is known as “Spaces around operators”. To me, this is one of the most important style rules for any language. Although individual language’s style rules on this topic differ, having some form of spacing around operators, logic codes, and the like improve readability by boundless measures. Likewise, blank lines strategically placed between lines equally creates more understandable code.

function sayHi() {
  "use strict";
  /* Calculates if the user should be greeted or not */

var answerOne, answerTwo;
 if (12+2===14) {
 } else {answerOne=false;}
    if ("Oh my, it's a bear"==="There is a lion in the streets!") {answerTwo =true;}else{answerTwo = false;}

  // The user does not get to be greeted because they can add or read too well.
  if (answerOne&&!answerTwo) {
   console.log("Hi, user!"); }}

After reading that, new lines and spaces around operators are much more appealing, would you say? :P. Sharp-eyed readers may have noticed the jQuery style guide had words to say on white space, and they may be wondering why I inserted Python in here if I could have covered this topic in another style guide. For one thing, I find some of Python’s rules more relaxed than jQuery’s. There are also other sections in PEP8 that I like and implement in my code. The fact I started out programming in Python might have an effect on this as well. šŸ˜›

The best style guide: yours!

Hopefully you are not overwhelmed by all these guidelines. In your pursuit of clean code, there is one important concept to remember: they are only suggestions! These are not hard-and-fast laws you absolutely must follow or others will see you as in inferior programmer. On the contrary, these are merely suggestions, guidelines, if you will, intended to help you (and others, if it is a collaborative project) produce better code. As I said at the beginning and I as alluded to in the last section, there may be “rules” so to speak you like from one but prefer another or have personal preference on some matters. In this case, you do something everyone does: makes their own style guide! By combining the majority of one guide along with parts of others and your own taste, you create the best style guide for you: your own! Code Guide mentioned this principle from the beginning.

Golden rule
Enforce these, or your own, agreed upon guidelines at all times. Small or large, call out what’s incorrect.

Everyone has their own guide. No single guide can please everyone. In fact, even in languages that have only style guide, such as Python and PEP8, there are personal variations to otherwise consistent styling. If you are confused over which to “obey”, make your own and stick to it. Be sure to revise your guidelines though, as they are always living documents that do and should change with coding habits and trends.

Take note, though, that you are not required to physically or digitally write down your own style guide. Although you can if you want to, chances are you will stop very quickly early on. The reason is simple: usually your changes are “exceptions”, modifications to a rule in a larger superset of rules. To write out your entire style guide means you will copy and paste write out every rule in the master files (themselves living documents and subject to revision) and make note of the relatively miniscule changes you made.

Now, I am not saying you can never write them down. If you want to note your personal changes in order to learn them, by all means do it! Some people actually publish their style guide for the sake of others, either for discussion or for others to follow if they want to collaborate on a project.

One final note: as you continue to code, your guide will become second nature to you and so ingrained in your head your code will follow the guide without you even noticing most of it. Yet there will be times you are wondering about a certain part (maybe you haven’t coded something that applied to the section of the guide in a while) so you look up what the rules say. In this case, you will look at what the master guide you are using says on the subject. The majority of the time though, you will glide on by without giving it a second thought. šŸ™‚

Linters are your friend

As I previously wrote, a linter is defined as a tool that checks your code for errors, be it syntax or visual in nature. If you have not started using them yet, now is a great time to start. Every single HTML, CSS, and JavaScript linter stated (with the exception of the W3C validators) have options that can be configured to support your personal, handpicked styling. While you may not be able to configure it for every little detail (I have yet to find out if JSHint will check for spaces for operators, for example), most of them are already configured to follow the universal standards “out of the box”. That means once you specify your “rules”, you have something to use strictly hold you accountable for any errors made.

PHEW! Now that WAS a lot of reading, wasn’t it![1] I told you there was a lot we would cover. Hopefully you know have a deeper understanding and respect for clean code and are already developing your own personal style guide by which you will abide. šŸ™‚


One thought on “Web Coding Style Guides

Comments are closed.