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

Commits
HTML
Pug
CSS
CSS Preprocessors
JavaScript
Boilerplate
References
Translations

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

Pug Syntax
Pug Comments
Pug Base Code

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

CSS Syntax
CSS Declaration Order
CSS Class Name
CSS Performance
CSS Media Queries

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

Code Guide by @mdo
idiomatic CSS
idiomatic.js
Zeno Rocha Coding Style
Airbnb JavaScript Style Guide

9. Translations

Português (Brasil)
Russian (by Vbifonixor)

Files

README.md

Latest commit

History

README.md

File metadata and controls

My Coding Style

Summary

1. Commits

2. HTML

HTML Summary

2.1. HTML Syntax

2.2. HTML Comments

2.3. HTML Character Encoding

2.4. HTML Attribute Order

2.5. HTML Performance

2.6. HTML Base Code

3. Pug

Pug Summary

3.1. Pug Syntax

3.2. Pug Comments

3.3. Pug Base Code

4. CSS

CSS Summary

4.1. CSS Syntax

4.2. CSS Declaration Order

4.3. CSS Class Name

4.4. CSS Performance

4.5 CSS Media Queries

5. CSS Preprocessors

CSS Preprocessors Summary

5.1. CSS Preprocessors Syntax

5.2. CSS Preprocessors Performance

5.3. CSS Preprocessors Media Queries

5.4. CSS Preprocessors Comments

6. JavaScript

JavaScript Summary

6.1. JavaScript Syntax

6.2. JavaScript Variables

6.3. JavaScript Performance

6.4. JavaScript and HTML5 Data Attributes

6.5. JavaScript Comments

7. Boilerplate

8. References

9. Translations