Fluent Conf: Maintainable JavaScript

Nicholas C. Zakas (WellFurnished) @slicknet
Code Style / Programming Practices

Below are my notes from Zakas’ presentation at Fluent Conf; slides can be viewed with slideshare.

Why Write Maintainable Code

Most of the time you’re maintaining code
Maintainability is good for the business, your code is supposed to keep working after you leave.
Your co-workers care a lot about your code
Pretty much everybody learned (front-end developers) on their own.
- They all code the best way (rock stars)
- Be on a team, let go of the rock star mentality; teams succeed (minus Tennis)

Style Guide

Code style is the way developers communicate code 2 code
Donald Knuth (is my homeboy): “Programs are meant to be read by humans, and only incidentally for computers to execute.”
Idiomatic: https://github.com/rwldrn/idiomatic.js
Crockford’s code conventions: http://javascript.crockford.com/code.html
Google’s style guide: http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml
JQuery Core Style Guidelines: http://docs.jquery.com/JQuery_Core_Style_Guidelines
What’s important is that there is ONE way to do it
The less code on one line, the less likely you will encounter a merge conflict!

Commenting

Self-documenting code is a myth perpetuated by those who hate to write documentation
Like seasoning, just enough is the right amount of code commenting
Difficult to understand code needs comments!
Code that might seem wrong when you first look at it needs comments (I meant to do that!)
Browser specific code to support a hack for IE needs comments

Naming

Use logical names for variables & functions
Don’t worry about length
You are communicating with yourself and other developers
- Verbs do stuff, use for methods
- Nouns are things, properties
Avoid useless names
camelCase is a good standard for variables and functions
- What about acronyms? new XMLHttpRequest() use upper or camelCase, not both, please.
Constant-like varibles: HOVER_CLASS
Constructor functions should have the first letter in Uppercase

Programming Practices

Do not have HTML strings in your JavaScript
Do not have JavaScript in your HTML
Do not have a JavaScript expression in CSS
Keep CSS out of JavaScript, go to CSS and style it
Many people write event handlers the wrong way, they should be very small and only handle events themselves, e.g. call other functions.
Don’t pass the event object around, WHY? If you want to call the function somewhere else you need the event, and you won’t know what specfic data is needed from the event object
- Event handlers should pass relevant data to a standard function
Don’t modify objects you don’t own; adding methods to prototype, other people have an expectation about how the API is supposed to work, when you change that you create a mine field
Avoid global function and variables
Throw your own errors! this is a really, really helpful thing.
- “I don’t like when I get errors and I have no idea where they are coming from”
- Put method the name and a message in the error.
- Just in the places where you are likely to cause an error
- Or, when you are creating an API, just to help people out
Avoid null comparisons, use instanceof to test for specifit object types
- object instanceof MyType
- typeof null is equal to object
Separate config data from methods, keep data out of application logic, changing data should not introduce errors
- All URLs should be pulled out of JavaScript logic
- Any settings, repeated unique values
Props2js: https://github.com/nzakas/props2js

Automation

Build, adding removing debugging code, validating code, minifying code, etc.
- http://code.google.com/p/js-build-tools/
- UglifyJS, Closure Compiler, https://ant.apache.org, https://github.com/cowboy/grunt introducting grunt