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 to have a place for myself and other developers who participate in my projects able to inform the coding standards used.

Like this is a new document, some rules may not have been applied in old projects.

This is a living document and changes can occur at any time.

1. Commits

For facilitate the contribution of any people in projects, all commit message, pull request title or issue discussion must be in English.

Before commit adjusts in project, check if exists one open issue and make references for this issue using '#' in your commit message.

// Good
git commit -m "Add placeholder in input #10"

// Bad
git commit -m "Add placeholder in input"

2. HTML

The main influence for the HTML rules is the Code Guide by @mdo.

HTML Summary

[HTML Syntax] (#html-syntax)
[HTML Comments] (#html-comments)
[Character Encoding] (#html-encoding)
[Attribute Order] (#html-attribute-order)
[HTML Performance] (#html-performance)
[HTML Base Code] (#html-base)

2.1. HTML Syntax

Use soft tabs with two spaces. You can configure your editor for this.

<!-- Good -->
<nav class="nav">
  <ul class="nav-menu">
    <li class="nav-item">
      <a class="nav-link">

<!-- Bad-->
<nav class="nav">
      <ul class="nav-menu">
            <li class="nav-item">
                  <a class="nav-link">

Always use double quotes.

<!-- Good -->
<div class="main">

<!-- Bad-->
<div class='main'>

Don't include a / in self-closing elements.

<!-- Good -->
<hr>

<!-- Bad-->
<hr />

2.2. HTML Comments

Follow this rule to add comments in HTML.

<!-- This is a good example -->
<!-- /Closing a good example -->

2.3. 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="toggle" 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 -->
<script src="scripts.min.js"></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 http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="format-detection" content="telephone=no">
<meta name="viewport" content="width=device-width">
 
<link rel="shortcut icon" href="assets/img/ico/favicon.ico" />

<!-- SVG Logo --> 
<link rel="logo" type="image/svg" href="../assets/img/logo/logo.svg" />
 
<title></title>

<link rel="stylesheet" href="assets/css/style.css" />
 
</head>
<body>

<!-- Scripts -->
<script src="assets/js/scripts.min.js"></script>

</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. CSS

The main influences for the CSS rules are Code Guide by @mdo and idiomatic CSS.

CSS Summary

[CSS Syntax] (#css-syntax)
[CSS Declaration Order] (#css-order)
[CSS Class Name] (#css-class-name)
[CSS Performance] (#css-performance)
[Mobile First and Media Queries] (#css-media-querie)
[Pre-processors] (#css-pre-processors)
[CSS Comments] (#css-comments)

3.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 brace 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 and shorthand hex values and avoid specifying units is zero-values.

/* Good */
.selector-1 {
  color: #aaa;
  margin: 0;
}
 
/* Bad */
.selector-1 {
  color: #AAAAAA;
  margin: 0px;
}

3.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;
}

3.3. CSS Class Name

Keep classes lowercase and use dashes.

/* Good */
.nav-item { ... }
 
/* Bad */
.NavItem { ... }
.nav_item { ... }

Dashes serve as natural breaks in related class. Prefix classes based on the closest parent or base class.

/* Good */
.navbar { ... }
.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 { ... }

3.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 classes.

/* 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 { ... }

3.5 Mobile First and Media Queries

Start the development with generic rules 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 { ... }
}

3.6. Pre-processors

I use pre-processors in all projects. Today I use LESS.

Warning with nesting rules of pre-processors. Continue keep without nesting.

/* Good */
.nav-item { ... }

/* Bad */
.navbar { 
  .nav { 
    .nav-item { 
      ... 
    }
  }
}

Provide generic names with variables.

/* Good */
@brand-primary: #049cdb;

/* Bad */
@color-blue: #049cdb;

3.7. CSS Comments

All comments must be made using the syntax of the preprocessor in use.

//
// Section
// --------------------------------------------------

// Sub-section
// --------------------------------------------------

//
// Commentary block
// 
//

// Commentary

ktpm489/coding-style