javascript-best-practice

A collection of JavaScript Best Practices

Much like being in shape, writing consistent, maintainable and performant code does not have to be "aspiration", its a decision we make and stick to. If you see someone writing junk, share this with them!

Short List

Use the “Good Parts” (and avoid the “Bad parts”)
Clear, Concise and Commented Code
Meaningful Variable Names (Especially as Parameters)
Avoid Global Variables
Use JSLint to ensure your code is consistent.
Always Unit Test your Code (even for simple/quick fixes and one-liners)
Learn (“Real”/”Raw”) JavaScript (fundamentals) before using Libraries like JQuery/Backbone
Avoid Libraries/Modules/Frameworks until you understand them, especially when they are un-tested/documented if(tests===false) alert(“Don’t use it!”)
Never Commit/Ship Broken/Buggy Code even when “PMs” Pressure You!
Its only “Done” when its “Documented”.

Extra Mile

~~Learn CoffeeScript it will Set you Free!~~
Learn & Use Patterns
(Don’t be afraid to) Critique someone else’s code if they ignore any coding best practices (by pointing to the specific “guideline” that is not being followed)
Compile your code with Source Maps (to aid debugging)

My ambition is to write a system that automatically reviews ("lints") JavaScript code while you are writing it and rejects code that does not adhere to these best practices.

Recommendations from Maintainable JavaScript

Maintainable JavaScript (Nicholas C. Zakas 2010) has many practical JavaScript best practices. I highly recommend you buy & read his book: http://www.amazon.com/Maintainable-JavaScript-Nicholas-C-Zakas/dp/1449327680/

Indentation

Indentation should be four spaces not tabs.

// Good
if (true) {
    makePandaHappy();
}

Line Length

Lines should be no longer than 80 characters. Lines which go over 80 char should be wrapped after an operator (e.g. comma). The continuation line should be indented two levels (8 chars).

// Good
registerNewUser(firstName, lastName, emailAddress, password,
        preferredLanguage);

// Bad: Continuation line only indented four spaces
registerNewUser(firstName, lastName, emailAddress, password,
    preferredLanguage);

registerNewUser(firstName, lastName, emailAddress, password
        , preferredLanguage);

Note: there are plenty of advocates for "Leading Comma" or "Trailing Comma" see: http://www.sencha.com/forum/showthread.php?6796-Leading-comma-or-Trailing-comma-that-is-the-question.

Primitive Literals

Strings

Always use double quotes and span a single line.

// Good
var message = "Welcome to JayessVille!";

// Bad: Single Quotes
var message = 'single quotes confuse. avoid';

CoffeeScript

I am a huge fan of CoffeeScript's elegance and simplicity. But its not as popular as I would have liked. :-(

I actually find CoffeeScript incredibly easy to read (practice?) but I agree with @pgte its harder to get contributions from others for open source projects if they are written in CoffeeScript, simply because not that many people know the language! :-(

I still recommend you learn coffeescript, its so much more fun to write and (with practice) read than JavaScript! And for small teams where everyone learns it, CoffeeScript wipes the floor with JavaScript!

Further discussion:

http://net.tutsplus.com/articles/interviews/should-you-learn-coffeescript/
http://stackoverflow.com/questions/2954557/has-anyone-used-coffeescript-for-a-production-application
https://tech.dropbox.com/2012/09/dropbox-dives-into-coffeescript/
Why CoffeeScript? http://vimeo.com/35258313
Try CoffeeScript: http://coffeescript.org/ [click Try]
REPL: http://repl.it/languages/CoffeeScript
Intro: http://youtu.be/QgqVh_KpVKY

Book

The Little Book on CoffeeScript: http://www.amazon.com/dp/1449321054/ Available FREE at: http://arcturo.github.io/library/coffeescript/index.html

Learn By Doing

Learn CoffeeScript by Testing with the “Koans”: https://github.com/sleepyfox/coffeescript-koans

Small Stack of Best Books

While I'm a strong advocate of learning by doing, sometimes it pays to learn from the knowledge/mistakes of more experienced people by reading the books they have written...

I keep a small stack of the best titles on my desk to recommend to my "junior" developers:

If you live in London and can't afford to buy books, message me on LinkedIn, I'm happy to give you any of my books in exchange for insights. :-)

Test Driven Development - Writing Reliable Code

If you are not doing Test Driven Development (TDD), you officially an amateur; go do your homework! But seriously, testing is easy and will give you confidence in the code you have written.

Writing comprehensive tests allows you to refactor your code as you learn how to do things more efficiently (natural progression - you’re meant to keep learning; honing your craft!) and can build on your existing codebase without fear of breaking existing (decoupled) modules.

There are a wide range of options for testing JavaScript: See: http://stackoverflow.com/questions/300855/looking-for-a-better-javascript-unit-test-tool

I recommend reading http://www.amazon.com/dp/0321683919/ and http://www.amazon.com/dp/1449323391/ to get a good understanding of the available options.

I have used:

Vows: http://vowsjs.org/
Mocha: http://mochajs.org/
Jasmine: https://jasmine.github.io/
Chai: http://chaijs.com/
JS-Test-Driver: https://code.google.com/p/js-test-driver/
NodeJS Assert (core module): http://nodejs.org/api/assert.html

And of these I favor Jasmine for its Simplicity. (but always keep open mind if someone has experience of others)

Jasmine

Background: https://github.com/jasmine/jasmine/wiki/Background
Try: http://tryjasmine.com/?
Tutorial: http://net.tutsplus.com/tutorials/javascript-ajax/testing-your-javascript-with-jasmine/
More: https://github.com/jasmine/jasmine/wiki
Download: https://github.com/jasmine/jasmine/releases
GitHub repo: https://github.com/jasmine/jasmine
Using Jasmine in Node.js (server side) https://github.com/mhevery/jasmine-node
Another good tutorial: http://evanhahn.com/?p=181

Notes

Sources

History

This originally started out in a Google Doc: https://docs.google.com/document/d/1t9msoVNY5KlRnHeIAgUgqDyaXh2Q35v5zHtdpZ2vy-U I created it to share/suggest best practices with my team of developers. The idea was that all developers in the company could edit the doc and a generally agreed code for writing code could be established.

The reality was that I was the only one who even looked at the Google Doc! Nobody made any comments or contributions. :-( Too "Busy" coding to stop and think: "Is my code consistent...?" or "Is this maintainable by someone else?" ... This is not the time or place to voice my frustration at trying to get people in an established organisation (with more bad habits than you can imagine) to adopt industry best practices for JavaScript code. Each to their own.

Its time to put this up on GitHub for a wider audience to access. ;-)

dwyl / javascript-best-practice