Preserving Coding Standards: 5 Tools to Get You Started

There are numerous resources we can lean on during coding that will help preserve standards across the team. In this tutorial, we are going to look into how to deploy and use five of these tools.

Introduction

HTML, CSS, and JavaScript are particularly easy-going where the matter of writing conventions is concerned. As long as certain notations follow the language rules, that the quotes, brackets, colons, semi-colons and so on are all in the right place, the code will work. However, indentation, spacing, line breaking, declaration order of properties, functions and variables, including their word-casing are entirely up to the authors.

HTML elements, for example, are not actually case-sensitive. We can write them lowercase or uppercase; what was a common practice back in the 90’s. Additionally, wrapping attribute values in quotes has been optional since the arrival of HTML5, something few people actually do. All this allows the code below to be declared valid per the HTML5 standard:

/** Valid HTML in HTML **/<BLOCKQUOTE class=pull-quote id=quote-1><P>Content precedes design. Design in the absence of content is not design, it’s decoration.</P><FOOTER>— Jeffrey Zeldman</FOOTER></BLOCKQUOTE>

In CSS, some prefer using space over tab—or vice versa—for indentation. Properties within style rules can be arranged in any order. The presence of duplicates in your CSS is perfectly fine (most of the time), and in the case of CSS Pre-processors excessive nesting of style rules is perfectly doable.

.site {
	.header {&.logo {
		}
		.navigation {
			.menu {
				.menu-link {&:hover {

					}
				}
			}
		}
	}
}

Likewise, a JavaScript variable can be expressed with uppercase or lowercase, a single letter variable is acceptable, and omitting braces around conditional or loop blocks is also workable.

if(n < 3) doFunction();
while(!n < 3) n++;

The way we write code does not actually matter that much in terms of execution. But when working on a project with many people contributing to the code base, you will soon find the code base become a mess if each contributor is following their own preference. On a large scale project, it may cause complicated bugs, code may become less manageable, and would be a real pain for anyone who inherits and maintains the project in the future.

In short, it is encouraged to adopt a “Coding Standard”.

What Are Coding Standards?

“Coding Standards” are any set of rules which are agreed upon by those involved, when contributing to the project code base. They pave the standard for syntaxing to maintain consistency and clarity of the code, the formatting for readability, the use of common best practices of the language; often with some addition of proprietary rules unique to the project.

Harry Roberts, in his CSS Guidelines:

“In working on large, long-running projects, with dozens of developers of differing specialties and abilities, it is important that we all work in a unified way in order to — among other things — keep stylesheets maintainable; keep code transparent, sane, and readable, keep stylesheets scalable;”

Douglas Crockford, who popularized JSON in his “Code Conventions for the JavaScript Programming Language” stated:

“The long-term value of software to an organization is in direct proportion to the quality of the code base. Over its lifetime, a program will be handled by many pairs of hands and eyes. If a program is able to clearly communicate its structure and characteristics, it is less likely that it will break when modified in the never-too-distant future. Code conventions can help in reducing the brittleness of programs.

All of our JavaScript code is sent directly to the public. It should always be of publication quality. Neatness counts.”

Should I Create My Own Coding Standard?

The short answer is “not necessarily”, especially considering there are already dozens of commonly used style guides in the wild, For example:

• Code Guide, a complete set of guideline for HTML, CSS, and JavaScript by Mark Otto, the person behind Bootstrap.
• Idiomatic CSS by Necolas, who created arguably the most popular CSS reset ever, Normalize.css
• Airbnb CSS / SCSS and JavaScript Styleguide
• Wikimedia CSS and LESS Styleguide
• Google Style Guide for HTML, CSS, JavaScript among other languages
• jQuery JavaScript Style Guide
• WordPress CSS, JavaScript, and PHP Coding Standard

These style guides are well written, in depth and quite self-explanatory in terms of the reasoning behind each rule they impact. So, rather than composing our own style guide, it may be wiser to adopt and adapt existing patterns to fit it into our project right away.

The real question now is how do we keep everyone following the standards we choose?

Preserving Coding Standards

Fortunately, there are a couple of resources we can lean on during the development process that will help preserve standards across the team. In this tutorial, we are going to look into how to deploy and use some of these tools.

1. EditorConfig

EditorConfig is a dot file which registers a few basic formatting rules such as the indentation, whitespace, and new lines breaking. It works universally to any type of language and is already integrated in almost all code editors and IDEs such as Visual Studio, Sublime Text, Vim, and TextMate via plugins.

Deployment

Assuming you are using Sublime Text, the easiest way to install the plugin is through the PackageManager.

• Go to Tools > Command Palette.
• Type Install Package.
• Search and install “EditorConfig”.
• Once the plugin has been installed, create a .editorconfig in root directory of the project that will apply the specified configurations through all the files including ones within the sub-directories.
• Add EditorConfig properties to define code formatting–the following is a common generic example:

root = true

[*]
charset = utf-8
indent_style = tab
indent_size = 4
insert_final_newline = true

Use

Granted the configuration from our example, we will find our code indented with tab, and add a new line at the end of the file as you save it.

The configuration will affect all existing files where you might have previously used space indentation.

Refer to Supported Properties for applicable properties to the .editorconfig file, and the EditorConfig Wildcard Patterns to apply the properties for specific files or directories. You can also find list the plugin of your preferred editor or IDEs in the Download section.

2. CSSComb

According to the CodeGuide guideline, style properties should be grouped in accordance to the following consecutive order.

1. Positioning: position, top, left, etc.
2. Box Model: width, height, display, etc.
3. Typographic: font, line-height, etc.
4. Visual: background, border, border-radius, etc.

For example:

.body-content
{
    position: absolute;
    top: 0;
    left: 0;

    padding: 10px 12px;

    display: none;

    font-size: .8em;
    font-weight: bold;
    line-height: 26px;

    color: #fff;
}

If you adopt a guideline with a similar rule, in which properties are grouped in that certain order, CSSComb will really come in handy. Not only does it allow you to do exactly this, but additionally retains several style conventions such as spacing, the use of quotes, braces, colon, semi-colon, leading zero for length value, and it works nicely with CSS Pre-processor syntax.

Deployment

• Install CSSComb binary through npm install csscomb -g
• Create .csscomb.json in the root directory of the project, or within the directory where the CSS files are stored.
• Add CSSComb configurations in .csscomb.json. Check against the complete list of applicable options. To make it easier, you can generate the config file through the Config Builder webapp, or use any of the preset configurations which can be found in the repository.

Use

Use the csscomb command, like so:

csscomb assets/css/style.css

If you prefer, you can run CSSComb during the build process with the Gulp or Grunt plugin. Alternately, you can use a plugin in your code editor like Sublime Text and run it through the Command Palette. There is also a plugin available for Brackets and Atom.

3. StyleLint

StyleLint is a tool which examines our CSS against more than a hundred pre-defined rules, producing warnings in the case of violations. Some of these violations are easy to fix with the CSSComb, making these tools great to use hand in hand. CSSLint is also a perfect tool to perform a code review.

Deployment

• Install Stylint binary: npm install stylelint -g
• Create .stylelintrc file in the root directory of your project.
• Include the rules in .stylelintrc file, for example:

{
	"rules": {
		"color-hex-case": "lower",
		"color-hex-length": "short",
		"comment-empty-line-before": "always",
		"selector-no-combinator": true,
		"selector-no-id": true,
		"string-quotes": "double",
		"selector-no-type": true,
		"selector-no-universal": true,
		"selector-no-vendor-prefix": true
	}
}

A full list of applicable Stylint rules can be found on the Rules page.

Use

Use Stylelint through the command line (eg: stylelint "css/*.css"), PostCSS with the plugin, or install a plugin that will allow you to see the warnings directly within your code editor. The plugin is currently available for Sublime Text, Atom, and Visual Studio.

4. JSCS (JavaScript Code Style)

As the name implies, JSCS evaluates your JavaScript code styles; from the use of whitespace, functions and variable naming conventions, comment blocks, line breaks, and a lot more. JSCS has been used widely in popular open-source projects such as jQuery, Bootstrap, and Ember.js, and also by notable companies like Yandex and Adobe. Testament indeed; you probably should use it in your project as well!

Deployment

• Install JSCS CLI via npm install jscs -g.
• Create .jscsrc.
• Define and configure the rules. Alternately, use one of the preset configurations derived from popular projects such as "jquery", "airbnb", "google", "yandex", and "wordpress".

{
    "preset": "wordpress",
    "requireCurlyBraces": true
}

Use

Assuming your JavaScript file is stored in js/app.js, run the command: jscs js/app.js.

To fix the code styles, run jscs js/app.js --fix. In Sublime Text you can install JSCS Formatter to do so without leaving the code editor. A similar plugin called JSCS Fixer is also available for Atom.

5. JSHint

Another tool that I use daily to check my JavaScript is JSHint. Unlike JSCS, JSHint evaluations revolve around code validity, instead of merely the code styling. In addition, JSHint will also remove stylistic rules in the next release, since JSCS has been growing traction and does the job well on that specific matter. As such JSHint will only check against the use of variables, loops, comparison operators, scopes, nesting level, and the likes of other technical JavaScript stuff which possibly cause issues or bugs.

Deployment

• Install JSHint binary globally via npm install jshint -g
• Create a file named .jshintrc in the root directory of your project.
• Include JSHint rules in .jshintrc, for example:

{
	"boss": true,
	"eqeqeq": true,
	"eqnull": true,
	"expr": true,
	"immed": true,
	"noarg": true,
	"undef": true,
	"unused": true,
	"node": true
}

Use

Use the jshint command line. Assuming you have all your JavaScript files stored in a directory named js, run jshint js.

Alternately, use JSHint with the Gulp or Grunt plugin. Sublime Text or Atom users may install the linter interface for SublimeText, Atom, allowing you to see the error report directly in the code editor.

Tip: CodePen will also check your JavaScript for errors using JSHint; find this option in the JavaScript Settings panel:

Wrapping Up

If setting all these tools on your project might seem tedious, use Yeoman to put them together as a scaffold. Whenever you or your team are about to start a new project, you will only need to hit a single line command to get them ready in a couple of seconds. For more details follow the Envato Tuts+ course on how to Create a Custom Yeoman Generator.

Lastly, having these tools will not only help us to produce better code and minimize errors in our code, but they will train us to be better web developers. At first, you might find your code has lots of errors. But, you will soon be writing code with fewer errors, as you start becoming accustomed to the rules.