"Every line of code should appear to be written by a single person, no matter the number of contributors." - Chinese Proverb.
The following document describes the rules of writing in development languages that I use: HTML, CSS and JavaScript.
The idea of this repository is not to be a complete code guide. Only to have a place for myself and other developers who participate in my projects able to inform the coding standards used.
As this is a new document, some rules may not have been applied in old projects.
This is a live document and changes can occur at any time.
In order to facilitate the contribution by anyone in a project, all commit messages, pull request title or issues discussion must be in English.
Before commit adjusts in project, check if exists an open issue and make references for this issue using '#' in your commit message.
// Good
git commit -m "Add placeholder on input #10"
// Bad
git commit -m "Add placeholder on input"The main influence for the HTML rules is the Code Guide by @mdo.
- HTML Syntax
- HTML Comments
- HTML Character Encoding
- HTML Attribute Order
- HTML Performance
- HTML Base Code
Use soft tabs with two spaces. You can configure your editor for this.
<!-- Good -->
<nav class="navbar">
<ul class="nav">
<li class="nav-item">
<a class="nav-link">
<!-- Bad-->
<nav class="navbar">
<ul class="nav">
<li class="nav-item">
<a class="nav-link">Always use double quotes.
<!-- Good -->
<main class="main">
<!-- Bad-->
<div class='main'>Don't include a / in self-closing elements.
<!-- Good -->
<hr>
<!-- Bad-->
<hr />Separate block element by a blank line and agroup the inners block elements.
<!-- Good -->
<ul class="nav-tabs">
<li>...</li>
<li>...</li>
<li>...</li>
<li>...</li>
</ul>
<div class="tab-content">
...
</div>
<!-- Bad-->
<ul class="nav-tabs">
<li>...</li>
<li>...</li>
<li>...</li>
<li>...</li>
</ul>
<div class="tab-content">
...
</div>Follow this rule to add comments in HTML.
<!-- This is a good example -->
<!-- /Closing a good example -->Always use UTF-8 for character encoding.
<head>
<meta charset="UTF-8">
</head>HTML attributes should be in this order for facilitate the reading.
classid,namedata-*src,for,type,hreftitle,altaria-*,role
<a class="..." id="..." data-modal="#overlay" href="#">
<input class="form-control" type="text">
<img class="img-rounded" src="..." alt="...">No need to specify a type when including CSS and JavaScript files as text/css and text/JavaScript.
<!-- Good -->
<link rel="stylesheet" href="assets/css/style.css">
<script src="scripts.min.js"></script>
<!-- Bad -->
<link rel="stylesheet" href="assets/css/style.css" type="text/css">
<script src="scripts.min.js" type="text/JavaScript"></script>
</head>
<body>For a better performance, all JavaScripts files must be at the end of the code. Before closing the <body>.
<!-- Good -->
<script src="scripts.min.js"></script>
</body>
<!-- Bad -->
<script src="scripts.min.js"></script>
</head>
<body>Always minify the code in projects only in HTML. Task builders like Grunt leaves this easier.
<!-- Good -->
<html><head>...</head><body><div class="container">...</div></body></html>
<!-- Bad -->
<html>
<head>
...
</head>
<body>
<div class="container">
...
</div>
</body>
</html>The following code is a HTML base for faster start the projects.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="format-detection" content="telephone=no">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
<link rel="shortcut icon" href="assets/ico/favicon.ico">
<link rel="logo" type="image/svg" href="assets/img/logo/logo.svg">
<link rel="stylesheet" href="assets/css/style.css">
<title></title>
</head>
<body>
</body>
</html>For give support a olds Internet Explorer...
<!DOCTYPE html>
<!--[if IE]><![endif]-->
<!--[if IE 7 ]> <html lang="en" class="ie7"> <![endif]-->
<!--[if IE 8 ]> <html lang="en" class="ie8"> <![endif]-->
<!--[if IE 9 ]> <html lang="en" class="ie9"> <![endif]-->
<!--[if (gt IE 9)|!(IE)]><!--><html lang="en"><!--<![endif]-->
<head>
...Currently using Pug like template engine.
Use soft tabs with two spaces. You can configure your editor for this.
//- Good
nav.navbar
ul.nav
li.nav-item
a.nav-link
//- Bad
nav.navbar
ul.nav
li.nav-item
a.nav-linkAlways use single quotes.
//- Good
button.btn(data-component='collapse')
//- Bad
button.btn(data-component="collapse")Insert the title of block, separate block element by a two blanks lines and agroup the inners block elements.
//- Good
//- Header
//- ===================================
header.header(role='banner')
a.logo(href='#', role='logo')
//- Main
//- ===================================
main.main(role='main')
section.content
//- Bad
header.header(role='banner')
a.logo(href='#', role='logo')
main.main(role='main')
section.contentFollow this rule to add comments in Pug.
//- This is a good example
// This is a bad example The comments using //- not is compiled on final code.
The following code is a Pug for faster start the projects.
doctype html
html(lang='en')
head
meta(charset='utf-8')
meta(name='description', content='')
meta(name='viewport', content='width=device-width, initial-scale=1.0, user-scalable=no')
meta(name='format-detection', content='telephone=no')
//- Title
//- ===================================
title
//- Favicon and SVG logo
//- ===================================
link(rel='shortcut icon', href='ico/favicon.ico')
link(rel='logo', type='image/svg', href='svg/logo/logo.svg')
//- Stylesheet and fonts
//- ===================================
link(href='css/style.css', rel='stylesheet')
body The main influences for the CSS rules are Code Guide by @mdo and idiomatic CSS.
Use soft tabs with two spaces. You can configure your editor for this.
/* Good */
.nav-item {
display: inline-block;
margin: 0 5px;
}
/* Bad */
.nav-item {
display: inline-block;
margin: 0 5px;
}Always use double quotes.
/* Good */
[type="text"]
[class^="..."]
.nav-item:after {
content: "";
}
/* Bad */
[type='text']
[class^='...']
.nav-item:after {
content: '';
}Include a single space before the opening bracket of a ruleset.
/* Good */
.header {
...
}
/* Bad */
.header{
...
}Include a single space after the colon of a declaration.
/* Good */
.header {
margin-bottom: 20px;
}
/* Bad */
.header{
margin-bottom:20px;
}Include a semi-colon at the end of the last declaration in a declaration block.
/* Good */
.header {
margin-bottom: 20px;
}
/* Bad */
.header{
margin-bottom:20px
}Keep one declaration per line.
/* Good */
.selector-1,
.selector-2,
.selector-3 {
...
}
/* Bad */
.selector-1, .selector-2, .selector-3 {
...
}Single declarations should remain in one line.
/* Good */
.selector-1 { width: 50%; }
/* Bad */
.selector-1 {
width: 50%;
}Separate each ruleset by a blank line.
/* Good */
.selector-1 {
...
}
.selector-2 {
...
}
/* Bad */
.selector-1 {
...
}
.selector-2 {
...
}Use lowercase, shorthand hex values and avoid specifying units is zero-values.
/* Good */
.selector-1 {
color: #aaa;
margin: 0;
}
/* Bad */
.selector-1 {
color: #AAAAAA;
margin: 0px;
}The declarations should be added in alphabetical order.
/* Good */
.selector-1 {
background: #fff;
border: #333 solid 1px;
color: #333;
display: block;
height: 200px;
margin: 5px;
padding: 5px;
width: 200px;
}
/* Bad */
.selector-1 {
padding: 5px;
height: 200px;
background: #fff;
margin: 5px;
width: 200px;
color: #333;
border: #333 solid 1px;
display: block;
}Keep class lowercase and use dashes to separate the classname.
/* Good */
.page-header { ... }
/* Bad */
.pageHeader { ... }
.page_header { ... }Use single dash to element name, double underline to element block and double dash to style modification.
/* Good */
.page-header__action { ... }
.page-header__action__title { ... }
.page-header--active { ... }
.btn { ... }
.btn--primary { ... }
/* Bad */
.page-header-action { ... }
.page-header-action-title { ... }
.page-header-active { ... }
.btn { ... }
.btn-primary { ... }Dashes and underline serve as natural breaks in related class. Prefix class based on the closest parent or base class.
/* Good */
.nav { ... }
.nav__item { ... }
.nav__link { ... }
/* Bad */
.item-nav { ... }
.link-nav { ... }Avoid giving too short names for class and always choose meaningful names that provide the class function.
/* Good */
.btn { ... }
.page-header { ... }
.progress-bar { ... }
/* Bad */
.s { ... }
.ph { ... }
.block { ... }Never use IDs.
/* Good */
.header { ... }
.section { ... }
/* Bad */
#header { ... }
#section { ... }Do not use selectors standards for not generic rules, always preferably for class.
/* Good */
.form-control { ... }
.header { ... }
.section { ... }
/* Bad */
input[type="text"] { ... }
header
sectionAvoid nesting elements, the preference is always to use class.
/* Good */
.navbar { ... }
.nav { ... }
.nav__item { ... }
.nav__link { ... }
/* Bad */
.navbar ul { ... }
.navbar ul li { ... }
.navbar ul li a { ... }Nest only when need change the class comportament with interference for other class. Keep the nested on max of three elements.
/* Good */
.modal-footer .btn { ... }
.progress.active .progress-bar { ... }
/* Bad */
.modal-btn { ... }
.progress.active .progress-bar .progress-item span { ... }Always minify the CSS code. Task builders like Grunt leaves this easier.
<!-- Good -->
.navbar { ... }.nav { ... }.nav-item { ... }.nav-link { ... }
<!-- Bad -->
.nav-item {
...
}
.nav-link {
...
}Start the development with generic rules with and add media queries with mobile first.
/* Good */
.navbar {
margin-bottom: 20px;
}
@media (min-width: 480px) {
.navbar {
padding: 10px;
}
}
@media (min-width: 768px) {
.navbar {
position: absolute;
top: 0;
left: 0;
}
}
@media (min-width: 992px) {
.navbar {
position: fixed;
}
}
/* Bad */
.navbar {
position: fixed;
top: 0;
left: 0;
}
@media (max-width: 767px) {
.navbar {
position: static;
padding: 10px;
}
}Keep the media queries as close to their relevant rule sets whenever possible. Don't bundle them all in a separate stylesheet or at the end of the document.
.navbar { ... }
.nav { ... }
.nav-item { ... }
@media (min-width: 480px) {
.navbar { ... }
.nav { ... }
.nav-item { ... }
}I use pre-processors in all projects. Today I use Stylus, but some projects use LESS.
- CSS Preprocessors Syntax
- CSS Preprocessors Performance
- CSS Preprocessors Media Queries
- CSS Preprocessors Comments
Use soft tabs with two spaces. You can configure your editor for this.
// Good
.nav-item
display inline-block
// Bad
.nav-item
display inline-block Do not use semi-colons, commas or brackets
// Good
.header
position fixed
top 0
right 0
left 0
// Bad
.header {
position: fixed;
top: 0;
right: 0;
left: 0;
}Keep one declaration per line.
// Good
.selector-1,
.selector-2,
.selector-3
...
// Bad
.selector-1, .selector-2, .selector-3
... Separate nested ruleset by a blank line and blocks ruleset by a double blank line.
// Good
.navbar
margin 0 0 20px
li
display inline-block
.nav
display block
li
float left
// Bad
.navbar
margin 0 0 20px
li
display inline-block
.nav
display block
li
float leftUse $ for the variables.
// Good
$gray-darker = #111
$gray-dark = #393C45
$gray = #555
$gray-light = #aaa
$gray-lighter = #ECF1F5
$gray-white = #fbfbfbWarning with nesting rules of preprocessors. Continue keep without nesting.
// Good
.nav-item
...
// Bad
.navbar
.nav
.nav-item
... Do not use @extends, always use mixins.
reset(arg = '')
if (arg == list)
margin 0
padding-left 0
list-style none
if (arg == form)
background 0
border 0
padding 0
.nav
reset(list)
.btn
reset(form)Provide the media queries rules inside the element.
.navbar
position absolute
top 5px
z-index 5
@media (min-width $screen-sm)
position fixed
margin-right $space-sm
@media (min-width $screen-md)
right 0
top 10px Provide one summary on header of files.
//
// Variables
//
// 1. Colors
// 2. Spaces
// 3. Media Queries
// 4. Typography
//
// ==================================================
//
// 1. Colors
// --------------------------------------------------
...
//
// 2. Spaces
// --------------------------------------------------
...For main element.
//
// 1. Header
// --------------------------------------------------
... For children elements.
// 1.1 Header Item
// --------------------------------------------------
...For generic comments
// Simple comment
// Block
// Comment
...The main influences for the JavaScript rules are idiomatic.js and Zeno Rocha Coding Style.
- JavaScript Syntax
- JavaScript Variables
- JavaScript Performance
- JavaScript and HTML5 Data Attributes
- JavaScript Comments
Use soft tabs with two spaces. You can configure your editor for this.
// Good
while (condition) {
statements
}
// Bad
while (condition) {
statements
}Always use semicolons.
// Good
var me = $(this);
test();
// Bad
var me = $(this)
test()Always use single quotes.
// Good
var string = '<p class="foo">Lorem Ipsum</p>';
var noteClick = me.attr('data-note');
// Bad
var string = "<p class='foo'>Lorem Ipsum</p>";
var noteClick = me.attr("data-note");Keep else in the same line of closure of the if.
// Good
if ( true ) {
...
} else {
...
}
// Bad
if ( true ) {
...
}
else {
...
}Add spaces between operators.
// Good
for (i = 0; i < 10; i++) {
...
}
// Bad
for (i=0;i<10;i++) {
...
}Never add a space between the keyword function and the function name.
// Good
foo(function() {
...
});
// Bad
foo ( function () {
...
});Add spaces outside parentheses () but avoid it inside.
// Good
if (condition) {
statement
}
// Bad
if( condition ){
statement
}For conditionals always use curly brackets {}.
// Good
if (condition) {
statement
} else if (condition) {
statement
} else {
statement
}
// Bad
if (condition) statement;
else if (condition) statement;
else statement;For strict equality checks === should be used in favor of ==.
// Good
if (foo === 'foo') {
statement
}
// Bad
if (foo == 'foo') {
statement
}All variables should be declared before used.
// Good
var me = $(this);
var noteClick = me.attr('data-note');
notes[noteClick].play();
// Bad
notes[noteClick].play();
var me = $(this);
var noteClick = me.attr('data-note');Always use var to declare variables.
// Good
var me = $(this);
// Bad
me = $(this);Use JSHint to detect errors and potential problems.
Always minify and concat the JavaScript code. Task builders like Grunt leaves this easier.
Avoid using classes to start in a JavaScript interaction. To do so, use HTML5 Data Attributes.
// Good
$('[data-component="tab"]');
// Bad
$('.tab');This approach makes the classes are only responsible for styling.
Thus elements that share the same style, but do not have the same interaction, may function separately.
A single line above the code that is commented.
// Good
// Good example of comment
var me = $(this);
// Bad
var me = $(this); // Bad example of commentI have a boilerplate using this coding style.
It's call Kratos Boilerplate.