The simple documentation approach

Non-documentation is incredibly important to writing maintainable code, but it does have its limits. For instance, while you can use expressive variable names to describe many variables, you can't use them to describe parts of Backbone itself. For example, when a View takes a model option, the only way to rename it more expressively would be to create an entirely new property:

var BookView = Backbone.View.extend({
    initialize: function() {
        this.bookModel = this.model;
    }
});

Now, there is nothing wrong with the above code, but in some sense, it crosses the line between code as documentation and replacing documentation with code. In cases like these, a more natural solution may instead be to simply use a comment, as follows:

// This View takes a ""Book"" ModelBookView = Backbone.View.extend();

However, many programmers find that it's easy to miss such single-line comments, and therefore, they save them only for documenting specific lines of code. For class or method documentation, these developers rely on a specialized form of the multiline comment, which is marked with an extra leading asterisk and (optional) leading asterisks on each subsequent line:

/**
 * This View takes a ""Book"" Model
 */BookView = Backbone.View.extend();
When used this way throughout your code, these documentation sections form easy-to-read alternating blocks, making it trivial to skim through to what you're looking for without having to actually read the code in between:BookView = Backbone.View.extend({
    /**
     * This ""foo"" method does foo stuff
     */
    foo: function() {
        doSomeFooStuff();
    },
    /*
     * This ""bar"" method takes a ""Baz"" argument and does bar stuff
     */
    bar: function(baz) {
        doBarStuffWith(baz);
    }
});

Most modern code editors will color such documentation differently from the rest of the code as well, making it even easier to skim through.

By using a combination of these multiline comments for your classes and methods, and using single-line comments to explain the tricky code inside of functions, you can very effectively document what class of Model a View has or which routes use a particular View. Further, while writing such comments does take more time than relying on non-documentation, the few extra seconds that they take you to write could save you hours or even days of work later on.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.226.4.235