Code guide

This code guide is primarily for my own benefit (but feel free to use it also) so that when writing code and organizing files I can focus on solving problems without having to think too much about minor details such as code formatting. This article was inspired by codeguide.co.

Golden rule

Everything created should appear to have been done by a single person, no matter the number of contributors but don't be pedantic about upholding all of these rules where it may not be practical, it is a guide. Do all things in moderation, even moderation itself.

Global rules

These rules apply to all coding languages such as HTML, CSS, JavaScript, and PHP.

  • Use tabs for indentation and spaces for alignment.
  • Use underscores to represent a space and hyphens to represent... a hyphen (Wikipedia's URLs are a great example of why this is needed).
  • Always prefer using single quotes (they are easier to type).
  • Always prefer using lowercase letters (good for consistency and makes it easier to find things).
  • Use American spellings (the web was made by the Americans, hence the 'color' CSS property instead of 'colour').

HTML

Syntax
  • Don't omit optional closing tags (e.g. </p> or </li>)
  • Always provide a trailing slash on self-closing elements (so we clearly know where elements end).
  • Order attributes alphabetically (for consistency).
  • Don't insert blank line breaks, unless the line break is content within an element.
Doctype

Enforce standards mode to enable more consistent rendering and use lowercase letters as per our global rule (it's perfectly valid syntax and works across all browsers).

<!doctype html>
Required tags

You should always include these base tags in every HTML document:

<html>
	<head>
	</head>
	<body>
	</body>
</html>
HTML tag

Always include a dir and a lang attribute on the HTML element. Note that the lang attribute's value can be entirely lowercase (see rule 2.1.1.). The lang attributes value consists of something called subtags. You can mix and match those to your liking. "en-gb" is a language subtag followed by a regional subtag. Essentially you can have a language or variant subtag followed by an optional regional subtag. You can read this answer on StackOverflow for more info.

<html dir='ltr' lang='en-gb'>
Character encoding

For security and usability reasons always use a variant of UTF for your encoding. This means UTF-8, UTF-16 or UTF-32 depending upon your requirements. This tag should always be the very first after the opening head tag, even before any comments and ensure your files are actually encoded in UTF.

<head>
	<meta charset='utf-8'/>
</head>
HTML comments

Single line comments should be written like this:

<!-- My comment here. !-->

Multi-line comments should be written like this:

<div>
	<!--
	     There is a tab and five spaces before this line.
	     The same is true for this line.
	!-->
</div>
CSS and JS includes

Don't bother specifying the type attribute.

<!-- Good !-->
<link href='main.css' rel='stylesheet'/>
<script src='main.js'></script>

<!-- Bad !-->
<link href='main.css' rel='stylesheet' type='text/css'/>
<script src='main.js' type='text/javascript'></script>
Boolean attributes

For boolean attributes, their presence is enough for a true and absence is enough for a false. Do not apply values to these attributes.

<!-- Good !-->
<input checked type='checkbox'/>

<!-- Bad !-->
<input checked='checked' type='checkbox'/>

CSS

Syntax
  • Use hyphens to separate words in class names and likewise (this goes against our global rule but this design choice has been embedded in the spec itself).
  • Each selector should be on its own line.
  • Blank line breaks should separate each selector/definition.
  • The opening brace should be on the last selector's line and have a single space before it.
  • The closing brace should be on its own line.
  • Each declaration should be on its own line.
  • Each declaration's : should have a single space after it.
  • Each declaration should end with ;, including the last line.
  • Every comma separated value should have a single space after it.
  • When leading zeros can be omitted, do not omit them, e.g. write 0.5 even though you could write .5
  • Use single quotes within attribute/value selectors, e.g. write [type='text'] instead of [type=text]
  • When declaring a zero value don't specify units, e.g. write margin: 0; instead of margin: 0px;.
  • When writing hex colors use shorthand if possible.

Example:

/* Good */
[data-selector='selector'],
#selector,
.selector,
.selector > a:hover {
	background: rgba(0, 0, 0, .25);
	box-shadow: 0 1px 1px rgb(0, 0, 0), inset 0 1px 0 #ff0;
	margin: 0;
	position: static;
}

a {
	color: #0f0;
}

PHP

Instead of writing out all of the rules in a long and (probably hard to read) list, I will instead provide examples of good ways to write code.

Indentation
<?php
echo 'Good. Do not think you need to indent because of the PHP opening tag.';
Set up
<?php
namespace My\Namespace;

use Something\Somewhere;
use Stuff\SomewhereElse;

class Something {
	use SomeTrait, AnotherTrait;

	const IMPORTANT_DATA = 'String.';
	const IMPORTANT_DATA_2 = 2;

	public $property = true;
	public $property_2 = false;

	private $something = 1;
	private $something_else = 2;

	protected $var = 1;
	protected $var_2 = 2;

	public static function doSomething($var) {
		return $var += 1;
	}
}
Language constructs

See this answer on StackOverflow for more information.

echo 'Good.';
include 'good.php';
Statements
if ($x > $y) {
	echo 'X is greater than Y.';
}

for ($x = 0; $x < $y; $x += 1) {
	doSomething($x);
}

foreach ($things as $thing) {
	doSomething($x);
}

foreach ($things as $thing_key => $thing) {
	doSomething($x);
}

switch ($x) {
	case 1:
		echo '1.';
		break;
	case 2:
		echo '2.';
		break;
	case 3:
	case 4:
	case 5:
		echo '3, 4, and 5.';
		break;
	case 6:
	case 7:
		doSomething($x);
		/* fall through */
	case 8:
		doSomethingElse($x);
		break;
	default:
		echo 'No break is needed.';
}
Naming conventions
$variable_name = '';

function function_name($var) {
	return $var += 1;
}

class StudlyCaps {
	$property_name = true;

	private function methodName() {
	}
}
Miscellaneous
$x = true;
$anonymous_function = function () use ($x) {
	if ($x === true) {
		return true;
	} else {
		return false;
	}
};

if (
	($user &&
		$user->address &&
		$user->address->country &&
		$user->address->country->code
	) &&
	($user->isActive())
) {
	echo $user->address->country->code;
}

$sql = '
	SELECT
		*
	FROM `table`
	LEFT JOIN `table_2` USING (`column`)
	WHERE `column_2` = TRUE
	AND `column_3` = FALSE
	GROUP BY `column_4`;
';
0 comments

Comments (0)

Your comment