Coding and Style guide

So you've come up with a great exercise, but you're not sure how to get it to fit with the rest of the Khan Academy exercises. What should your code look like? Are there any tips and tricks to follow to make an exercise especially good?

Code with Style

Overall

For all of our code, we try to stick to a 80 character line limit.

Javascript

For our Javascript, we tend to follow the jQuery style guide with a few exceptions:

• we use 4 space indents instead of tabs.
• we use $ rather than jQuery
• we do not use the liberal spacing with square brackets and parens as indicated in the style guide, except within object literals. That is, if-expressions, loop conditions, and functions should follow normal, tight wrapping:

For example, we do stuff like this:

if (condition) {
    functionCall(bar, ["hi"], function() {
        return 42;
    });
    return { color: "red" };
}

And not like this:

if ( condition ) {
    functionCall( bar, [ "hi" ], function (){
        return 42;
    } );
    return {color: "red"};
}

HTML

For our HTML, we try to use common sense, and make it look like the surrounding HTML. Try to not use custom styles as much as possible. You can check out a few of our exercises to see what it currently looks like.

Coding best practices

We like to keep our codebase clean, so that things are easy to change and easy to understand. In general, don't try to do anything terribly fancy with your code. As a few overall principles, we try to:

Use as little code as possible

Don't do something with 100 lines when it can be done in 10. This makes it immensely easier for us to test your code and make sure everything will work great.

Don't do lots of logic within <var> tags

Although <var> tags are very useful because they allow you to execute useful code, try to keep that code to a minimum.

Don't use a util file unless it can be used in other exercises

While it may be easier to code something up using a real javascript file, it clutters our codebase too much if the javascript can't be used in more than one context.

Try to use behavior in utils (like math and word-problems especially)

If possible, try to make your output fit into a form that can be used by our current utilities. For example, try using randRange instead of making your own random function, or using toSentence to turn a list into a string of sentence-like text.

Make sure what you're coding hasn't been done before

If you think something you're making looks like something we're using already, try to go find it! Especially, check out our Utility Module Reference to check out the stuff we've done using utils already.

Favor underscore.js instead of loops

We like to use the functional programming style of underscore.js instead of an imperative style to simplify a lot of our code. For example, when iterating through a list we like to use

_.each(myList, function(e) {
    // handle each element here
});

instead of

for (var i = 0; i < myList.length; i++) {
    // handle each element here
}

Don't do randomness anywhere except in the .vars tag

In order to make sure that our exercises are correctly randomly generated, avoid using any randomly generating functions outside of the initial .vars declarations.