Skip to content

Styleguide

Jump to bottom Edit New page
Flore edited this page Nov 13, 2017 · 2 revisions

Styleguide

This is a guide for writing consistent and aesthetically pleasing code. Please make sure you work with the code you are handed and not against it. When you can look at a file and know who edited it, you know you got a problem.

Content

General

Tips

  • Use tabs for indentation
  • Use UNIX-style newlines \n.
  • Avoid trailing whitespace.
  • Use as much whitespace as you can to make code human readable
  • Use comments and extensively document your code
  • Encode all your documents in UTF8

⬆ back to top

Common pitfalls

Concatenation and position

Concatenate all CSS and JS files into as little files as possible while still keeping your environment maintainable. JS should not be in the head as it will block your page from rendering until it is fully loaded.

Right

<html>
	<head>
		<link href="assets/theme/css/theme.min.css" rel="stylesheet" type="text/css">
		<link href="assets/css/site.min.css" rel="stylesheet" type="text/css">
	</head>
	<body>
		content

		<script src="assets/theme/js/theme.min.js" type="text/javascript"></script>
		<script src="assets/js/site.js" type="text/javascript"></script>
	</body>
</html>

❗ Wrong

<html>
	<head>
		<link href="assets/theme/css/theme.min.css" rel="stylesheet" type="text/css">
		<link href="assets/css/site.css" rel="stylesheet" type="text/css">
		<link href="assets/css/header.css" rel="stylesheet" type="text/css">
		<link href="assets/css/footer.css" rel="stylesheet" type="text/css">
		<link href="assets/css/footer.css" rel="stylesheet" type="text/css">
		<script src="assets/theme/js/theme.min.js" type="text/javascript"></script>
		<script src="assets/js/site.js" type="text/javascript"></script>
		<script src="assets/js/someotherscript.js" type="text/javascript"></script>
	</head>
	<body>
		content

		<script src="assets/theme/js/theme.min.js" type="text/javascript"></script>
		<script src="assets/js/functions.js" type="text/javascript"></script>
	</body>
</html>

Put your JS files right before the closing body tag.

Minification

All JS and CSS files need to be minified for production. This means no unnecessary white space, long variable names or comments to keep the size down and performance up.

Right

#wrapper{width:100%}.header{text-align:center;position:relative}.img-banner{width:100%;height:100%}.overlay{position:absolute;top:0;left:0;margin:0 auto}

❗ Wrong

#wrapper{
	width: 100%;
}
/* Header portion with usage and other comments */
	.header{
		text-align: center;
		position: relative;
	}
		.img-banner{
			width: 100%;
			height: 100%;
		}
	.overlay {
		position: absolute;
		top: 0;
		/* width: 980px; */
		left: 0;
		margin: 0 auto;
	}

Right

"use strict";var App=function(){return{debugging:function(n,o){console.log(n+o)}}}();

❗ Wrong

'use strict';


var App = (function() {

	//------------------------------------------------------------------------------------------------------------------------------------------------------------
	// settings
	//------------------------------------------------------------------------------------------------------------------------------------------------------------
	return {

		//----------------------------------------------------------------------------------------------------------------------------------------------------------
		// debugging prettiness
		//
		// text  {string}   Text to be printed to debugger
		// code  {keyword}  What kind of urgency: report,error,interaction
		//----------------------------------------------------------------------------------------------------------------------------------------------------------
		debugging: function( text, code ) {

			console.log( text + code );

		}

	}

}());

Inline JS

Inlining JS makes maintenance very difficult plus each <script> tag will block the browser from rendering anything below until the JavaScript is executed. Please do not inline your JS. Put it into a file and reference it at the bottom of the page.

Right

<body>
	<main class="container">
		<div class="row">
			<div class="col-sm-12">
				<a class="btn btn-soft" href="?more-info">More info</a>
			</div>
		</div>
	</main>

	<script src="js/functions.js" type="text/javascript"></script>
</body>

❗ Wrong

<body>
	<main class="container">
		<div class="row">
			<div class="col-sm-12">
				<a class="btn btn-soft" href="?more-info">More info</a>

				<script>
					$("body").css("visibility", "hidden");
					var locURL = location.href;
					var splitUrl = locURL.split('/');

					moreCode() {
						var foo;
					}
				</script>
			</div>
		</div>
	</main>
</body>

Polyfills

Please don't use polyfills for rounded corners, CSS animations or other embellishments for older browsers. This just puts more constraints on modern browsers with little to no difference to the actual usability of the elements.

Animations

Always try to use CSS3 animations and trigger them with your JS. This will take advantage of CSS3s native animation(hardware acceleration) speed and keep older browsers/devices free of process-intensive animation-clutter.

Javascript

Try to use as little as possible and make sure your site works with JS disabled. Provide at least useful paths to non-JS users.

Less important

Please don't use any !important rules in your CSS as each of those rules trigger the browser to rerender the page, slowing down your site. It also makes it hard to maintain your selectors. Relying on specificity helps you maintain your code and helps the browser render your styles in order of importance.

⬆ back to top

HTML

Semantics

HTML5 provides us with lots of semantic elements aimed to describe precisely the content. Make sure you benefit from its rich vocabulary.

Right

<main>
	<article>
		<header>
			<h1>Blog post</h1>
			<p>Published: <time datetime="2015-02-21">21st Feb, 2015</time></p>
		</header>
		<p>…</p>
	</article>
</main>

❗ Wrong

<div id="main">
	<div class="article">
		<div class="header">
			<h1>Blog post</h1>
			<p>Published: <span>21st Feb, 2015</span></p>
		</div>
		<p>…</p>
	</div>
</div>

Make sure you understand the semantic of the elements you're using. It's worse to use a semantic element in a wrong way than staying neutral.

Right

<h1>
	<img alt="Company" src="logo.png">
</h1>

❗ Wrong

<h1>
	<figure>
		<img alt="Company" src="logo.png">
	</figure>
</h1>

Use buttons for javascript functions, not links.

Right

<button class="action-btn js-action">Click here!</button>

❗ Wrong

<a href="javascript:void(0);" onClick="action()">Click here!</a>

Note the above example also seperates concerns between model and view by using js- classes.

Brevity

Keep your code terse. Forget about your old XHTML habits.

Right

<!doctype html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<title>Contact</title>
		<link rel="stylesheet" href="style.css">
	</head>
	<body>

		<h1>Contact me</h1>
		<input type="email" placeholder="you@email.com" required>
		<script src="main.js"></script>
	</body>
</html>

❗ Wrong

<!doctype html>
<html lang="en">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
		<title>Contact</title>
		<link rel="stylesheet" href="style.css" type="text/css" />
	</head>
	<body>
		<h1>Contact me</h1>
		<input type="email" placeholder="you@email.com" required="required" />
		<script src="main.js" type="text/javascript"></script>
	</body>
</html>

Accessibility

Accessibility shouldn't be an afterthought. You don't have to be a WCAG expert to improve your website, you can start immediately by fixing the little things that make a huge difference, such as:

  • learning to use the alt attribute properly
  • making sure your links and buttons are marked as such (no <div class=button> atrocities)
  • not relying exclusively on colors to communicate information
  • explicitly labelling form controls

Right

<h1><img alt="My Company, Inc." src="logo.png"></h1>

❗ Wrong

<h1><img alt="Logo" src="logo.png"></h1>

Language

While defining the language and character encoding is optional, it's recommended to always declare both at document level, even if they're specified in your HTTP headers. Favor UTF-8 over any other character encoding.

Right

<!doctype html>
<html lang="en">
	<meta charset="utf-8">
	<title>Hello, world.</title>
</html>

❗ Wrong

<!doctype html>
<title>Hello, world.</title>

Performance

Unless there's a valid reason for loading your scripts before your content, don't block the rendering of your page. If your style sheet is heavy, isolate the styles that are absolutely required initially and defer the loading of the secondary declarations in a separate style sheet. Two HTTP requests is significantly slower than one, but the perception of speed is the most important factor.

Right

<!doctype html>
<meta charset="utf-8">
<title>Hello, world.</title>
<p>...</p>
<script src="analytics.js"></script>

❗ Wrong

<!doctype html>
<meta charset="utf-8">
<script src="analytics.js"></script>
<title>Hello, world.</title>
<p>...</p>

⬆ back to top

LESS

Naming conventions

Class names should be specific

Use class names that are as short as possible but as long as necessary.

Right

.navigation
.author
.header
.info-box
.maps

❗ Wrong

.nav
.atr
.a
.b

Classes are all lower case

Right

.headline
.mapbox

❗ Wrong

.headLine
.mapsBox

Use dash for chaining words in classes

box-header
a-really-long-chain-of-classes
parent-name-child-name

Parent class names should be repeated for nested elements

E.g. [parent]-[child]-[subchild]

.maps
	.maps-header
	.maps-content
		.maps-content-box
	.maps-footer

Adding classes to an existing element repeats it's nested position in its name

.maps {
	.maps-box-small
	.maps-box-highlight
}

Never attach CSS rules to js- classes

⬆ back to top

Javascript

Use Semicolons, Commas

Use semicolons and commas wherever you can to help make each line reusable. Even though Javascript does not require a semicolon on it's last declaration, including it gives you the ability to move each line everywhere without worrying about trailing elements.

Right

target: {
	files: [
		'**/*.js',
	],
	tasks: [
		'concat',
		'clean',
		'wakeup',
	],
},

❗ Wrong

target: {
	files: [
		'**/*.js'
	],
	tasks: [
		'concat',
		'clean',
		'wakeup'
	]
}

Consider this scientific research.

160 characters per line

Limit your lines to 160 characters. Yes, screens have gotten much bigger over the last few years, but your brain has not. Use the additional room for split screen. However don't write long logical chains or comments in one line. Make use of whitespace.

Use single quotes

Use single quotes, unless you are writing JSON.

Right

var foo = 'bar';

❗ Wrong

var foo = "bar";

Opening braces go on the same line

Your opening braces go on the same line as the statement.

Right

if(true) {
	console.log('winning');
}

❗ Wrong

if(true)
{
	console.log('losing');
}

One space between conditions and its opening brace

Your opening braces go on the same line as the statement.

Right

if(true) {
	console.log('winning');
}

for(i = 0; i < 5; i++) {
	console('');
}

❗ Wrong

if (true) {
	console.log('winning');
}

for (i=0;i<5;i++) {
	console('');
}

Also note the whitspace in the for loop declaration

Declare one variable per var statement

Declare one variable per var statement, it makes it easier to re-order the lines.

Right

var keys   = ['foo', 'bar'];
var values = [23, 42];

var object = {};
while(keys.length) {
	var key = keys.pop();
	object[key] = values.pop();
}

❗ Wrong

var keys = ['foo', 'bar'],
		values = [23, 42],
		object = {},
		key;

while(keys.length) {
	key = keys.pop();
	object[key] = values.pop();
}

Use lowerCamelCase for variables, properties and function names

Variables, properties and function names should use lowerCamelCase. They should also be descriptive. Single character variables and uncommon abbreviations should generally be avoided.

Right

var adminUser = db.query('SELECT * FROM users ...');

❗ Wrong

var admin_user = db.query('SELECT * FROM users ...');

Use UpperCamelCase for class names

Class names should be capitalized using UpperCamelCase.

Right

function BankAccount() {
}

❗ Wrong

function bank_Account() {
}

Use UPPERCASE for Constants

Constants should be declared as regular variables or static class properties, using all uppercase letters.

Right

var SECOND = 1 * 1000;

function File() { }
File.FULL_PERMISSIONS = 0777;

❗ Wrong

const SECOND = 1 * 1000;

function File() { }
File.fullPermissions = 0777;

Use lowerCamelCase with a leading underscore for boolen statements

For boolen checks and conditions use an underscore and lowerCamelCase to name your variable.

Right

var _isOpen = element.hasClass('is-open');
function _hasPrivilege( user ) { }

❗ Wrong

var open = element.hasClass('is-open');
function return-privilege( user ) { }

Object / Array creation

Use trailing commas and put short declarations on a single line. Only quote keys when your interpreter complains:

Right

var a = ['hello', 'world'];
var b = {
	good: 'code',
	'is generally': 'pretty',
};

❗ Wrong

var a = [
	'hello', 'world'
];
var b = {"weird": 'whitespace'
				, is generally: 'confusing'
				};

Use the === operator

Use the triple equality operator as it will work just as expected and adds a level of confidence.

Right

var a = 0;
if(a !== '') {
	console.log('winning');
}

❗ Wrong

var a = 0;
if(a != '') {
	console.log('losing');
}

Use multi-line ternary operator

The ternary operator should not be used on a single line. Split it up into multiple lines instead.

Right

var foo = (a === b)
	? 1
	: 2;

❗ Wrong

var foo = (a === b) ? 1 : 2;

Do not extend built-in prototypes

Do not extend the prototype of native JavaScript objects. Your future self will be forever grateful.

Right

var a = [];
if(!a.length) {
	console.log('winning');
}

❗ Wrong

Array.prototype.empty = function() {
	return !this.length;
}

var a = [];
if(a.empty()) {
	console.log('losing');
}

Use descriptive conditions

Any non-trivial conditions should be assigned to a descriptively named variable or function:

Right

var _isValidPassword = password.length >= 4 && /^(?=.*\d).{4,}$/.test(password);

if(_isValidPassword) {
	console.log('winning');
}

❗ Wrong

if(password.length >= 4 && /^(?=.*\d).{4,}$/.test(password)) {
	console.log('losing');
}

Write small functions

Keep your functions short. A good function fits on a slide that the people in the last row of a big room can comfortably read. So don't count on them having perfect vision and limit yourself to ~15 lines of code per function.

Return early from functions

To avoid deep nesting of if-statements, always return a function's value as early as possible.

Right

function _isPercentage(val) {
	if(val < 0) {
		return false;
	}

	if(val > 100) {
		return false;
	}

	return true;
}

❗ Wrong

function _isPercentage(val) {
	if(val >= 0) {
		if(val < 100) {
			return true;
		}
		else {
			return false;
		}
	}
	else {
		return false;
	}
}

Or for this particular example it may also be fine to shorten things even further:

function _isPercentage(val) {
	var _isInRange = (val >= 0 && val <= 100);
	return isInRange;
}

Name your closures

Feel free to give your closures a name. It shows that you care about them, and will produce better stack traces, heap and cpu profiles.

Right

req.on('end', function onEnd() {
	console.log('winning');
});

❗ Wrong

req.on('end', function() {
	console.log('losing');
});

No nested closures

Use closures, but don't nest them. Otherwise your code will become a mess.

Right

setTimeout(function() {
	client.connect( afterConnect );
}, 1000);

function afterConnect() {
	console.log('winning');
}

❗ Wrong

setTimeout(function() {
	client.connect(function() {
		console.log('losing');
	});
}, 1000);

Use slashes for comments

Use slashes for both single line and multi line comments. Try to write comments that explain higher level mechanisms or clarify difficult segments of your code. Don't use comments to restate trivial things.

Right

// 'ID_SOMETHING=VALUE' -> ['ID_SOMETHING=VALUE'', 'SOMETHING', 'VALUE']
var matches = item.match(/ID_([^\n]+)=([^\n]+)/));

// This function has a nasty side effect where a failure to increment a
// redis counter used for statistics will cause an exception. This needs
// to be fixed in a later iteration.
function loadUser(id, cb) {
	// ...
}

var isSessionValid = (session.expires < Date.now());
if (isSessionValid) {
	// ...
}

❗ Wrong

/* Execute a regex */
var matches = item.match(/ID_([^\n]+)=([^\n]+)/));

// Usage: loadUser(5, function() { ... })
function loadUser(id, cb) {
	// ...
}

// Check if the session is valid
var isSessionValid = (session.expires < Date.now());
// If the session is valid
if (isSessionValid) {
	// ...
}

Object.freeze, Object.preventExtensions, Object.seal, with, eval

Crazy stuff that you will probably never need. Stay away from it.

⬆ back to top

Angular

Please refer to this Angular Style Guide for more information.

⬆ back to top

};

Add a custom footer
Add a custom sidebar
Clone this wiki locally