Always use double quotes.
```
Don't include a `/` in self-closing elements.
```html
```
Separate block element by a blank line and agroup the inners block elements.
```html
...
...
```
### 2.2. HTML Comments
Follow this rule to add comments in HTML.
```html
```
### 2.3. HTML Character Encoding
Always use UTF-8 for character encoding.
```html
```
### 2.4. HTML Attribute Order
HTML attributes should be in this order for facilitate the reading.
1. `class`
1. `id`, `name`
1. `data-*`
1. `src`, `for`, `type`, `href`
1. `title`, `alt`
1. `aria-*`, `role`
```html
```
### 2.5. HTML Performance
No need to specify a type when including CSS and JavaScript files as `text/css` and `text/JavaScript`.
```html
```
For a better performance, all JavaScripts files must be at the end of the code. Before closing the ``.
```html
```
Always minify the code in projects only in HTML. Task builders like [Grunt](http://gruntjs.com/) leaves this easier.
```html
...
...
...
...
```
### 2.6. HTML Base Code
The following code is a HTML base for faster start the projects.
```html
```
For give support a olds Internet Explorer...
```html
...
```
## 3. Pug
Currently using Pug like template engine.
### Pug Summary
1. [Pug Syntax](#Pug-syntax)
1. [Pug Comments](#Pug-comments)
1. [Pug Base Code](#Pug-base)
### 3.1. Pug Syntax
Use soft tabs with two spaces. You can configure your editor for this.
```javascript
//- 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.
```javascript
//- 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.
```javascript
//- 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.
```javascript
//- 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.
```javascript
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](https://github.com/mdo/code-guide) and [idiomatic CSS](https://github.com/necolas/idiomatic-css/).
### CSS Summary
1. [CSS Syntax](#css-syntax)
1. [CSS Declaration Order](#css-order)
1. [CSS Class Name](#css-class-name)
1. [CSS Performance](#css-performance)
1. [CSS Media Queries](#css-media-queries)
### 4.1. CSS Syntax
Use soft tabs with two spaces. You can configure your editor for this.
```css
/* Good */
.nav-item {
display: inline-block;
margin: 0 5px;
}
/* Bad */
.nav-item {
display: inline-block;
margin: 0 5px;
}
```
Always use double quotes.
```css
/* 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.
```css
/* Good */
.header {
...
}
/* Bad */
.header{
...
}
```
Include a single space after the colon of a declaration.
```css
/* 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.
```css
/* Good */
.header {
margin-bottom: 20px;
}
/* Bad */
.header{
margin-bottom:20px
}
```
Keep one declaration per line.
```css
/* Good */
.selector-1,
.selector-2,
.selector-3 {
...
}
/* Bad */
.selector-1, .selector-2, .selector-3 {
...
}
```
Single declarations should remain in one line.
```css
/* Good */
.selector-1 { width: 50%; }
/* Bad */
.selector-1 {
width: 50%;
}
```
Separate each ruleset by a blank line.
```css
/* Good */
.selector-1 {
...
}
.selector-2 {
...
}
/* Bad */
.selector-1 {
...
}
.selector-2 {
...
}
```
Use lowercase, shorthand hex values and avoid specifying units is zero-values.
```css
/* 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.
```css
/* 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.
```css
/* Good */
.page-header { ... }
/* Bad */
.pageHeader { ... }
.page_header { ... }
```
Use single dash to element name, double underline to element block and double dash to style modification.
```css
/* 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.
```css
/* 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.
```css
/* Good */
.btn { ... }
.page-header { ... }
.progress-bar { ... }
/* Bad */
.s { ... }
.ph { ... }
.block { ... }
```
### 4.4. CSS Performance
Never use IDs.
```css
/* Good */
.header { ... }
.section { ... }
/* Bad */
#header { ... }
#section { ... }
```
Do not use selectors standards for not generic rules, always preferably for class.
```css
/* Good */
.form-control { ... }
.header { ... }
.section { ... }
/* Bad */
input[type="text"] { ... }
header
section
```
Avoid nesting elements, the preference is always to use class.
```css
/* 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.
```css
/* 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](http://gruntjs.com/) leaves this easier.
```css
.navbar { ... }.nav { ... }.nav-item { ... }.nav-link { ... }
.nav-item {
...
}
.nav-link {
...
}
```
### 4.5 CSS Media Queries
Start the development with generic rules with and add media queries with mobile first.
```css
/* 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.
```css
.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
1. [CSS Preprocessors Syntax](#preprocessors-syntax)
1. [CSS Preprocessors Performance](#preprocessors-performance)
1. [CSS Preprocessors Media Queries](#preprocessors-media-queries)
1. [CSS Preprocessors Comments](#preprocessors-comments)
### 5.1. CSS Preprocessors Syntax
Use soft tabs with two spaces. You can configure your editor for this.
```css
// Good
.nav-item
display inline-block
// Bad
.nav-item
display inline-block
```
Do not use semi-colons, commas or brackets
```css
// 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.
```css
// 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.
```css
// 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.
```css
// 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.
```css
// Good
.nav-item
...
// Bad
.navbar
.nav
.nav-item
...
```
**Do not use @extends**, [always use mixins](http://csswizardry.com/2016/02/mixins-better-for-performance/).
```css
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.
```css
.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.
```css
//
// Variables
//
// 1. Colors
// 2. Spaces
// 3. Media Queries
// 4. Typography
//
// ==================================================
//
// 1. Colors
// --------------------------------------------------
...
//
// 2. Spaces
// --------------------------------------------------
...
```
For main element.
```css
//
// 1. Header
// --------------------------------------------------
...
```
For children elements.
```css
// 1.1 Header Item
// --------------------------------------------------
...
```
For generic comments
```css
// Simple comment
// Block
// Comment
...
```
## 6. JavaScript
The main influences for the JavaScript rules are [idiomatic.js](https://github.com/rwldrn/idiomatic.js/) and [Zeno Rocha Coding Style](https://github.com/zenorocha/my-coding-style/).
### JavaScript Summary
1. [JavaScript Syntax](#js-syntax)
1. [JavaScript Variables](#js-variables)
1. [JavaScript Performance](#js-performance)
1. [JavaScript and HTML5 Data Attributes](#js-data-attributes)
1. [JavaScript Comments](#js-comments)
### 6.1. JavaScript Syntax
Use soft tabs with two spaces. You can configure your editor for this.
```js
// Good
while (condition) {
statements
}
// Bad
while (condition) {
statements
}
```
Always use semicolons.
```js
// Good
var me = $(this);
test();
// Bad
var me = $(this)
test()
```
Always use single quotes.
```js
// Good
var string = '
Lorem Ipsum
';
var noteClick = me.attr('data-note');
// Bad
var string = "
Lorem Ipsum
";
var noteClick = me.attr("data-note");
```
Keep `else` in the same line of closure of the `if`.
```js
// Good
if ( true ) {
...
} else {
...
}
// Bad
if ( true ) {
...
}
else {
...
}
```
Add spaces between operators.
```js
// 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.
```js
// Good
foo(function() {
...
});
// Bad
foo ( function () {
...
});
```
Add spaces outside parentheses `()` but avoid it inside.
```js
// Good
if (condition) {
statement
}
// Bad
if( condition ){
statement
}
```
For conditionals always use curly brackets `{}`.
```js
// 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 `==`.
```js
// Good
if (foo === 'foo') {
statement
}
// Bad
if (foo == 'foo') {
statement
}
```
### 6.2. JavaScript Variables
All variables should be declared before used.
```js
// 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.
```js
// Good
var me = $(this);
// Bad
me = $(this);
```
### 6.3. JavaScript Performance
Use [JSHint](http://www.jshint.com/) to detect errors and potential problems.
Always minify and concat the JavaScript code. Task builders like [Grunt](http://gruntjs.com/) 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***.
```js
// 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.
```js
// 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](https://github.com/LFeh/kratos-boilerplate).
## 8. References
* [Code Guide by @mdo](https://github.com/mdo/code-guide)
* [idiomatic CSS](https://github.com/necolas/idiomatic-css/)
* [idiomatic.js](https://github.com/rwldrn/idiomatic.js/)
* [Zeno Rocha Coding Style](https://github.com/zenorocha/my-coding-style/)
* [Airbnb JavaScript Style Guide](https://github.com/airbnb/JavaScript)
## 9. Translations
* [Português (Brasil)](/translations/pt-BR/)
* [Russian (by Vbifonixor)](https://github.com/vbifonixor/coding-style)