Coding standards

Keywords: 

We've already talked about coding standards for HTML and CSS. There's a complete list of standards.

Let's add some standards for JavaScript.

Indent

Indent code by four spaces inside braces (the {}, remember).

Check out this code. You don't need to understand what it does. Just look at the formatting.

/**
* Record new evil bunnies.
*/
EvilBunnies.recordNewBunnies = function() {
    //Get number of bunnies.
    var inputBunnies = $("#new-bunnies").val();
    //Check that input is not negative.
    if ( inputBunnies < 0 ) {
        alert("Sorry, can't have a negative number of bunnies.");
        return;
    }
    //Add to total. Need the parseInt so inputBunnies isn't
    //treated as a string.
    totalEvilBunnies += parseInt(inputBunnies);
    //Update bunnies count on the page.
    $("#number-bunnies").html(totalEvilBunnies);
};

Each time there's an opening brace (a {), add indenting. Each time there's a closing brace (}), remove it.

BTW, IDEs automatically indent JS.

Comments

Comments in JS are very important! They explain what the code does. When someone wants to change the code in the future, they'll need comments to understand it.

Here's that code once more. Check out the comments. Just look at the formatting, and the comments. You'll learn more about writing code like this later.

/**
* Record new evil bunnies.
*/
EvilBunnies.recordNewBunnies = function() {
    //Get number of bunnies.
    var inputBunnies = $("#new-bunnies").val();
    //Check that input is not negative.
    if ( inputBunnies < 0 ) {
        alert("Sorry, can't have a negative number of bunnies.");
        return;
    }
    //Add to total. Need the parseInt so inputBunnies isn't
    //treated as a string.
    totalEvilBunnies += parseInt(inputBunnies);
    //Update bunnies count on the page.
    $("#number-bunnies").html(totalEvilBunnies);
};

There are two comment styles in JS:

  • Multi-line
  • Single-line

A multi-line comment can be as long as you want:

/**
* Record new evil bunnies.
*/

Multi-line comments are often used before functions, to explain what functions do. The multi-line style is used at the top of a function, even if the comment has just one line, like the example you just saw. Multi-line comments help break up the code, so you can tell when new functions start.

Every line beginning with // is a single-line comment. The browser ignores everything from the // to the end of the line.

When do you add single-line comments? A good rule-of-thumb is to think about adding a comment every time you add a {.

You don't have to add comments for every piece of code. For example, look at this:

//Check that input is not negative.
if ( inputBunnies < 0 ) {
    alert("Sorry, can't have a negative number of bunnies.");
    return;
}

It's clear what that one alert() statement does, so I didn't add a comment before it.

However, I did a comment before the if, explaining what it does.

Variables names

Two things here. First, a variable's name should help you understand what the variable is for. This is important!

For example, this could be from an app for a K12 school:

if ( a < 13 ) {
    $("#f").show();
}

Huh? What is a? What is f? No idea.

Here's another version:

if ( studentAge < 13 ) {
    $("#parent-permission-slip-message").show();
}

Aha! If a student is less than 13 years old, then show a message, that we need a permission slip from a parent.

The code is easier to understand.

The other thing about variable names is that they are camel case. The first character is lowercase. If a variable name is multi-word, like studentAge, start each part with an uppercase character.

Exercise

Exercise: Format this
Download this messy file. Fix it, and put it on your server somewhere.

Submit the URL of your solution.

(If you were logged in as a student, you could submit an exercise solution, and get some feedback.)

CoolThing

Make the text on a page fade away.

Summary

  • Indent code wrapped in braces. Braces wrap code, making code blocks.
  • Comments are very good.
  • Use meaningful variable names.
  • Use camelCase variable names.