The non-documentation approach

First, let me clarify that the non-documentation approach doesn't mean avoiding documentation entirely. Rather, it relies on using forms of documentation other than explicit code comments.

For instance, consider the following line of code:

var Book = Backbone.Model.extend();

Now, if we had wanted to, we could have written a comment describing this line of code, as follows:

/**
 * This defines a book model.
 */Book = Backbone.Model.extend();

However, adding such a comment doesn't really tell us anything we don't already know, because our choice of variable name (Book) already tells us what the class is. Simply by choosing a descriptive variable name for our class, we have documented what it does, without the need of supplemental documentation.

However, the names of class variables aren't the only important names. Function names, and particularly, method names, can also be very helpful in explaining what the function/method does. Consider the following:

     bookNav: function() {
         router.navigate('bookPage', {silent: true, trigger: true});
    }
vs.:
     navigateSilentlyToBookPage: function() {
         router.navigate('bookPage', {silent: true, trigger: true});
    }

Just by typing a few extra characters we've eliminated the need to read the method's definition in order to understand it. Further, while reading, the definition might not seem so hard in this particular example; however, if the function were longer or more complex, it might not be so easy.

One other way that functions can be used to convey documentation is by breaking them up into separate functions. For instance, let's say we had a View method that incremented a counter, saved a Model, updated and then rendered another View method, and finally changed the URL, as follows:

    example: function(router) {
        this.model.set('counter', this.model.get('counter') + 1);
        this.model.save();

        this.siblingView.model = this.model;
        this.siblingView.render();

        var url = this.url();
        router.navigate(url, {silent: true, trigger: false});
    }

Naming such a method would be difficult:

"incrementCounterAndSaveModelAndUpdateAndRenderSiblingViewAndRefreshURL" doesn't roll off the tongue very well. You could simplify it to updateCounterAndRefresh, but then you'd lose some of the non-documentation that the more verbose name would provide.

A better approach is to use the simpler name but separate the parts of the method into their own methods, as follows:

    incrementCounterAndSave: function() {
        this.model.set('counter', this.model.get('counter') + 1);
        this.model.save();
    },
    updateAndRenderSiblingView: function() {
        this.siblingView.model = this.model;
        this.siblingView.render();
    },
    refreshURL: function(router) {
        var url = this.url();
        router.navigate(url, {silent: true, trigger: false});
    },
    updateCounterAndRefresh: function(router) {
        this.incrementAndSaveCounter();
        this.updateAndRenderSiblingView();
        this.refreshURL(router);
    }

As you can see the contents of our updateCounterAndRefresh method now read almost like an English documentation string, effectively documenting what's going on without any actual documentation. Furthermore, if we wanted to unit test this code (which we'll discuss in the following chapter), it will be far easier to do so with these separate methods than it would have been originally.

Moreover, the preceding code is a relatively simple example, while your actual methods may in fact be much longer than six lines. In real-world projects, it is even more important to utilize this technique of using many (well-named) methods rather than long monolithic methods, as it will greatly improve both the code's readability and ease of testing.

Class, function, and other variable names are not the only forms of non-documentation. File names and folder structure can also provide a great deal of information if used correctly. Consider a file named Book.js. On its own, we have no way of knowing whether this file contains a book Model, a book View, both, or something else entirely. However, if this file were renamed "BookView.js", it would be obvious. Similarly, if the file retained the name "Book.js" but was stored inside a "views" folder, the contents would again be apparent, without the requirement of any additional documentation.

Benefits of non-documentation for other approaches

Before we move on to the other two documentation approaches, it is worth noting that the strategies we just described aren't only useful if you choose the non-documentation approach. In fact, they are great advice for all programmers. No matter what documentation you generate to supplement your code, at the end of the day, you and your fellow developers are going to have to work with the code itself, not the documentation. By working to keep that code as readable and instructive as possible, you provide benefits that while not the same as those offered by explicit documentation, are none the less very valuable, particularly in the long run.

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

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