Coding Style Save
[outdated/deprecated] My rules coding for HTML, CSS and JavaScript development
My Coding Style
"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.
Summary
1. Commits
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"
2. HTML
The main influence for the HTML rules is the Code Guide by @mdo.
HTML Summary
- HTML Syntax
- HTML Comments
- HTML Character Encoding
- HTML Attribute Order
- HTML Performance
- HTML Base Code
2.1. HTML Syntax
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>
2.2. HTML Comments
Follow this rule to add comments in HTML.
<!-- This is a good example -->
<!-- /Closing a good example -->
2.3. HTML Character Encoding
Always use UTF-8 for character encoding.
<head>
<meta charset="UTF-8">
</head>
2.4. HTML Attribute Order
HTML attributes should be in this order for facilitate the reading.
-
class -
id,name -
data-* -
src,for,type,href -
title,alt -
aria-*,role
<a class="..." id="..." data-modal="#overlay" href="#">
<input class="form-control" type="text">
<img class="img-rounded" src="..." alt="...">
2.5. HTML Performance
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>
2.6. HTML Base Code
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>
...
3. Pug
Currently using Pug like template engine.
Pug Summary
3.1. Pug Syntax
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-link
Always 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.content
3.2. Pug Comments
Follow 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.
3.3. Pug Base 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
4. CSS
The main influences for the CSS rules are Code Guide by @mdo and idiomatic CSS.
CSS Summary
4.1. CSS Syntax
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;
}
4.2. CSS Declaration Order
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;
}
4.3. CSS Class Name
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 { ... }
4.4. CSS Performance
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
section
Avoid 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 {
...
}
4.5 CSS Media Queries
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 { ... }
}
5. CSS Preprocessors
I use pre-processors in all projects. Today I use Stylus, but some projects use LESS.
CSS Preprocessors Summary
- CSS Preprocessors Syntax
- CSS Preprocessors Performance
- CSS Preprocessors Media Queries
- CSS Preprocessors Comments
5.1. CSS Preprocessors Syntax
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 left
Use $ for the variables.
// Good
$gray-darker = #111
$gray-dark = #393C45
$gray = #555
$gray-light = #aaa
$gray-lighter = #ECF1F5
$gray-white = #fbfbfb
5.2. CSS Preprocessors Performance
Warning 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)
5.3. CSS Preprocessors Media Queries
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
5.4. CSS Preprocessors Comments
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
...
6. JavaScript
The main influences for the JavaScript rules are idiomatic.js and Zeno Rocha Coding Style.
JavaScript Summary
- JavaScript Syntax
- JavaScript Variables
- JavaScript Performance
- JavaScript and HTML5 Data Attributes
- JavaScript Comments
6.1. JavaScript Syntax
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
}
6.2. JavaScript Variables
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);
6.3. JavaScript Performance
Use JSHint to detect errors and potential problems.
Always minify and concat the JavaScript code. Task builders like Grunt leaves this easier.
6.4. JavaScript and HTML5 Data Attributes
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.
6.5. JavaScript Comments
A single line above the code that is commented.
// Good
// Good example of comment
var me = $(this);
// Bad
var me = $(this); // Bad example of comment
7. Boilerplate
I have a boilerplate using this coding style.
It's call Kratos Boilerplate.
8. References
9. Translations
Open Source Agenda Badge
