My Preferred JavaScript Code Conventions

Code conventions are so important, in my perspective. The code you write is not a child in solitude. It soon needs to “socialize”, meaning that, you have to write code which other developers can understand, or can understand easily. Three years ago, the JavaScript I wrote was so ugly that I didn’t even take a second look at it. Meanwhile, I didn’t know how to save my poor writing habits. Fortunately, a lot of great engineers helped me, including Dan (who I mentioned in About Me), and of course my husband Michael.

Consistency

Before I start listing my favorite coding principles, I want to emphasize consistency. Our preferences may differ, but I believe it is always good to keep your coding styles consistent, and stick to them throughout your code.

Naming

I always believe the code itself can be the best documentation. Worry about making variable names too long? JavaScript minification is a great remedy for it.

Avoid naming variables with single characters. One single character does not mean anything to me. If it does mean anything to me, it means this piece of code is done by laziness. The letters i and j are often used for indexing the loop. I would prefer to say something like somethingIndex. It can tell me immediately what this variable does.

var dogIndex,
    dogs = ['Doberman', 'Golden Retriever', 'JackRusselTerrier'],
    dogLength = dogs.length;

for (dogIndex = 0; dogIndex < dogLength; dogIndex++) {
    console.log(dogs[dogIndex]);
}

Name variables with appropriate casings. There are several different types of casings.

• Lower camel case: local variables and functions, prototype methods

  function getFirstChild(parent) {
      return parent.firstChild;
  }

• Upper camel case: prototype name

  function Dog(name, age) {
      this.age = age;
      this.name = name;
  }

• All caps: global variables, constant variables

  var BACKGROUND_LIGHT = '#ffffff';

Give a method with a name beginning with a verb. Even when you want to check some state, and wish to get a Boolean value, it is better to use a name beginning with is than only using an adjetive.

function getName() {
    return 'Grace';
}

function isLoaded() {
    return true;
}

Spell check your variables, please. Oftentimes, I saw typos in variable names. I was wondering if developers were too lazy to correct them, or they did not even notice that. Either way, they reflect how careless the developers are about their code. I wish my essays are having no typos when they are handed to others to review.

Indentation

This is a controversial topic. There are a lot of different indent styles. My favorite one is 1TBS (The One True Brace Style). To me, this style is more symmetrical, more elegant and more balanced. I don’t like the Allman style. If you don’t agree with me, please read the title again. 🙂

Breaking lines

List all the variable declarations in lines. In JavaScript, variable hoisting makes all the variable declared inside the same scope hoisted to the top of the scope. Therefore, oftentimes we list all the variables at the beginning of the scope. Below is the format I champion! It is straightforward and obvious.

var cell,
    cellIndex,
    row = new Row(),
    table = new Table();

However, there is a kind of line breaking format, which keeps all the variables without initial assignments in one line, and then the rest keep one variable per line, for example:

var cell, cellIndex,
    row = new Row(),
    table = new Table();

It could be better in aesthetics. I cannot think of a better reason for this mixed style. I don’t like it. To me, my eyes have to take a very close look at the variables and find what I’m looking for.

Long logics need to break. Sometimes, the statement inside an if is very long, which may contains many &&‘s and many ||‘s. It makes very hard to read. There are two ways to break the logic stings: breaking before the logic operators, and breaking after the logic operators. I like the latter one.

Comments

• On-line comment at the end of the statement. In my opinion, this kind of comments should not designed for documentation, but only side notes for developers.

  var i = 0;
  i++; //TODO: check if we need this.

• Multi-line comment at the top of the statements. To keep it consistent with JsDoc, I prefer two asterisks at the first line, a space before each of the rest of lines begins.

  /**
   * A class for defining dog
   */
  var Dog = function (name) {
      this.name = name;
  }

Conclusion

There are many other conventions I will continuously add to this post. Below are all my own opinions. No matter which kinds you like, it is always good to make sure the team on the same page of code conventions. It is always polite to ask on the first day of job what the code conventions are in the current team. It is always a good idea to present your team’s code conventions to new team members.