Skip to content

STYLE-GUIDE.md

Latest commit

 

History

History
389 lines (288 loc) · 8.42 KB

STYLE-GUIDE.md

File metadata and controls

389 lines (288 loc) · 8.42 KB

Indentation

When writing any block of code that is logically subordinate to the line immediately before and after it, that block should be indented two spaces more than the surrounding lines

  • Do not put any tab characters anywhere in your code. You would do best to stop pressing the tab key entirely.
  • Increase the indent level for all blocks by two extra spaces

    • When a line opens a block, the next line starts 2 spaces further in than the line that opened

      // good:
if(condition){
  action();
}

// bad:
if(condition){
action();
}

    • When a line closes a block, that line starts at the same level as the line that opened the block

      // good:
if(condition){
  action();
}

// bad:
if(condition){
  action();
  }

    • No two lines should ever have more or less than 2 spaces difference in their indentation. Any number of mistakes in the above rules could lead to this, but one example would be:

      // bad:
transmogrify({
  a: {
    b: function(){
    }
}});

    • use sublime's arrow collapsing as a guide. do the collapsing lines seem like they should be 'contained' by the line with an arrow on it?

Variable names

  • A single descriptive word is best.

    // good:
var animals = ['cat', 'dog', 'fish']

// bad:
var targetInputs = ['cat', 'dog', 'fish'];

  • Collections such as arrays and maps should have plural noun variable names.

    // good:
var animals = ['cat', 'dog', 'fish'];

// bad:
var animalList = ['cat', 'dog', 'fish'];

// bad:
var animal = ['cat', 'dog', 'fish'];

  • Name your variables after their purpose, not their structure

    // good:
var animals = ['cat', 'dog', 'fish'];

// bad:
var array = ['cat', 'dog', 'fish'];

Language constructs

  • Do not use for...in statements with the intent of iterating over a list of numeric keys. Use a for-with-semicolons statement in stead.

    // good:
var list = ['a', 'b', 'c']
for(var i = 0; i < list.length; i++){
  alert(list[i]);
}

// bad:
var list = ['a', 'b', 'c']
for(var i in list){
  alert(list[i]);
}

  • Never omit braces for statement blocks (although they are technically optional).

    // good:
for(key in object){
  alert(key);
}

// bad:
for(key in object)
  alert(key);

  • Always use === and !==, since == and != will automatically convert types in ways you're unlikely to expect.

    // good:

// this comparison evaluates to false, because the number zero is not the same as the empty string.
if(0 === ''){
  alert('looks like they\'re equal');
}

// bad:

// This comparison evaluates to true, because after type coercion, zero and the empty string are equal.
if(0 == ''){
  alert('looks like they\'re equal');
}

  • Don't use function statements for the entire first half of the course. They introduce a slew of subtle new rules to how the language behaves, and without a clear benefit. Once you and all your peers are expert level in the second half, you can start to use the more (needlessly) complicated option if you like.

    // good:
var go = function(){...};

// bad:
function stop(){...};

Semicolons

  • Don't forget semicolons at the end of lines

    // good:
alert('hi');

// bad:
alert('hi')

  • Semicolons are not required at the end of statements that include a block--i.e. if, for, while, etc.

    // good:
if(condition){
  response();
}

// bad:
if(condition){
  response();
};

  • Misleadingly, a function may be used at the end of a normal assignment statement, and would require a semicolon (even though it looks rather like the end of some statement block).

    // good:
var greet = function(){
  alert('hi');
};

// bad:
var greet = function(){
  alert('hi');
}

Supplemental reading

Comments

  • Provide comments when a new function is declared, explaining the use of the function .
  • Comment on what code is attempting to do, not how it will achieve it.

Padding & additional whitespace

  • Pad function invocations in parameters with a space
  • Otherwise no padding in parameters
//Good  
	function( bar, foo() );
function(foo, bar);

//Bad
function(temp, foo());
function( foo, bar );
  • Put else and else if statements on the same line as the ending curly brace for the preceding if block with one space between else conditional and brackets 
    // good:
if(condition){
  response();
} else {
  otherResponse();
}

// bad:
if(condition){
  response();
}
else{
  otherResponse();
}

Working with files

  • Do not end a file with any character other than a newline.

Opening or closing too many blocks at once

  • The more blocks you open on a single line, the more your reader needs to remember about the context of what they are reading. Try to resolve your blocks early, and refactor. A good rule is to avoid closing more than two blocks on a single line--three in a pinch.

    // bad:
_.ajax(url, {success: function(){
  // ...
}});

// good:
_.ajax(url, {
  success: function(){
    // ...
  }
});

Variable declaration

  • Use a new var statement for each line you declare a variable on.

  • Do not break variable declarations onto mutiple lines.

  • Use a new line for each variable declaration.

    // good:
var ape;
var bat;

// bad:
var cat,
    dog

Capital letters in variable names

  • Some people choose to use capitalization of the first letter in their variable names to indicate that they contain a [class](http://en.wikipedia.org/wiki/Class_(computer_science\)). This capitalized variable might contain a function, a prototype, or some other construct that acts as a representative for the whole class.
  • Use a capital letter only on functions that are written to be run with the keyword new.
  • Do not use all-caps for any variables. Some people use this pattern to indicate an intended "constant" variable, but the language does not offer true constants, only mutable variables. *Use camelCase.

Minutia

  • Don't rely on JavaScripts implicit global variables. If you are intending to write to the global scope, export things to window.* explicitly instead.

    // good:
var overwriteNumber = function(){
  window.exported = Math.random();
};

// bad:
var overwriteNumber = function(){
  exported = Math.random();
};

  • For lists, put commas at the end of each newline, not at the beginning of each item in a list

    // good:
var animals = [
  'ape',
  'bat',
  'cat'
];

// bad:
var animals = [
    'ape'
  , 'bat'
  , 'cat'
];

  • Use single quotes around JavaScript strings *Use double quotes in HTML tag attributes.

    // good:
var dog = 'dog';

// bad:
var dog = "dog";

HTML

  • Do not use ids for html elements. Use a class instead.

    <!-- good -->
<img class="lucy" />

<!-- bad -->
<img id="lucy" />

  • Do not include a type=text/javascript" attribute on script tags

    <!-- good -->
<script src="a.js"></script>

<!-- bad -->
<script src="a.js" type="text/javascript"></script>

Additional Style

  • Use default syntax for defaulting variables:
//good:
 function(bar){
  var bar = bar || 0;
}

//bad:
function(bar){
  var bar = bar ? bar : 0;
}
function(bar){
 if(!bar) {
  bar = 0
  } 
}

*No padding between function declaration and parameter list

//good:
var foo = function(bar){...};
//bad:
var foo = function (bar) {...};

*Avoid the use of anonymous functions

//good 
var doWork = function(a, b){
  return a + b;
}

var otherFunction = function(c, doWork);

or:

var otherFunction = function(c, function(a){
  doWork(a, b);
});

//bad
var otherFunction = function(c, function(a, b){
  return a + b;
});