"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.
For facilitate the contribution of any people in projects, 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 in input #10"
// Bad
git commit -m "Add placeholder in 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 -->
<div 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.
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="...">
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>
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">
<link rel="shortcut icon" href="assets/img/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>
<!-- 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>
...
The main influences for the CSS rules are Code Guide by @mdo and idiomatic CSS.
- CSS Syntax
- CSS Declaration Order
- CSS Class Name
- CSS Performance
- Mobile First and Media Queries
- Pre-Processors
- CSS Comments
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, 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.
/* Good */
.nav-item { ... }
/* Bad */
.NavItem { ... }
.nav_item { ... }
Dashes serve as natural breaks in related class. Prefix class 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 { ... }
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 {
...
}
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 LESS
.
Warning with nesting rules of pre-processors. Continue keep without nesting.
/* Good */
.nav-item { ... }
/* Bad */
.navbar {
.nav {
.nav-item {
...
}
}
}
Provide semantic names for variables.
/* Good */
@brand-primary: #049cdb;
/* Bad */
@color-blue: #049cdb;
All comments must be made using the syntax of the preprocessor in use.
//
// Section
// --------------------------------------------------
// Sub-section
// --------------------------------------------------
//
// Commentary block
//
//
// Simple commentary
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-toggle="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 comment
MIT License © Luiz Felipe Tartarotti Fialho