Back to Basics: Template-Driven Documentation

Documentation is something that some see as a necessary evil; others look at it as a needless chore better left to someone else; others still see documentation as the indicator of a job well done. Documentation templates can help bring all of these different perspectives together and write quality software that's easier and less expensive to maintain and extend.

Writing documentation is the art of adding remarks to software source code in an effort to make that source code easier to understand and manipulate. The easier source code is to understand, the easier it is to maintain. The easier it is to maintain, the faster defects can be detected and repaired. Speedy resolution to the problems that come up over time means less time, effort, and ultimately money is spent maintaining software.

A 2010 research brief published through the Massachusetts Institute of Technology (MIT) determined that between 60% - 80% of the effort invested in the lifetime of a typical software application revolved around maintaining that application. It's reasonable to infer that most of money invested in a typical application is spent maintaining said application. Therefore, it's prudent to take steps during the development of the application to facilitate simplified maintenance in the future.

One such step is the generation of quality documentation. As writing documentation can be seen as a chore or a luxury that the project's timeline simply cannot afford, how do we help developers write quality documentation quickly and easily?

Documentation Templates

One effective yet very simple tool to help developers write documentation is the use of documentation templates. Documentation templates are short blocks of comments that the developer can copy and paste into their source code and then complete with the appropriate and applicable details. These templates are formatted for the programming language and tools used by the team for the project.

Consider the following documentation taken from a recent Google Apps Script application:

    /**
    * does a specific user have access to read a file in 

    * Google Drive
    * @param {String} user_id - the id of the user to check
    * @param {String} file_id - the id of the Doc to check
    * @return {Boolean} true if the user has access; 

    * false, otherwise
    */
    function can_read_file (user_id, file_id) {

This example uses JSDoc to get the developer started, but it's the bare minimum; many useful details have been omitted. For example, who wrote the function originally? Which developers have changed it since the function's inception? What happens if the user or the file don't exist? Does each call to the function result in an API request, or are the results cached (and if so, how long)? A more interesting example may look like this:

    /**
    * @summary true only if a user may read a file
    * @description does a specific user have access to read 

    * a file in Google Drive? true if yes
    *
    * @author Wes Dean <Wesley.Dean@example.com>
    * @version 1.0.2
    * @param {String} user_id - the id of the user to check
    * @param {String} file_id - the id of the Doc to check
    *
    * @return {Boolean} true if the user has access; false,

    * otherwise
    * @throws exception if either the user of the file 

    * doesn't exist
    *
    * @example
    * var has_access = can_read_file (someUser, someFile);
    *
    * @caching
    * the result of the API (user id / file id) tuple is 

    * cached in the memcache for future reference 

    * indefinitely; Google Drive Push Notifications will

    * tell us if the file is changed at which point we'll 

    * delete the result from the cache
    *
    * @history
    * 1.0 (Wes Dean): initial function
    * 1.0.1 (John Blaze): only check for read access, not write

    * access
    * 1.0.2 (Wes Dean): cache results from API call
    */

   function can_read_file (user_id, file_id) {

This example provides more information that may be usable by a developer to see exactly what a function does, how it go to its current state, how to use the function, etc..  The documentation also explains how caching may affect the function.

Building a Template

The next step is to build a template that can incorporate these concepts and can be quickly modified.

    /**
    * @summary short description
    * @description longer description goes here
    *
    * @author user <user@example.tld>
    * @version version number
    * @param {type} parameter name - parameter description
    *
    * @return {type} description of what's returned
    * @throws description of exceptional conditions
    *
    * @example
    * provide example of use
    *
    * @caching
    * description of how caching affects this function (remove 

    * if not applicable)
    *
    * @history
    * major.minor.patch (who) did what
    */
This documentation template can be copied and pasted directly into a project's source code; then, the developer can modify the content depending on how the function is used. The bold sections are meant to be replaced by the developer on a use-by-use basis.

Notice that there are several JSDoc tags that are not a part of the JSDoc specification. These tags - @caching and @history - are used to know how caching may affect the function and who should be contacted for questions that arise from various changes in the code.

Benefits

This template helps developers quickly document their code. Completing the template only takes a minute or two while the explicitly provided sections and tags make sure that the developer provides sufficient details to meet the ongoing needs of the team. Moreover, the template helps developers new to the project to quickly come up to speed with the standards established for the project.

A side-effect of using templates such as these is that it becomes (more) evident to developers that they're trying to fit too much functionality into a single function. That is, if the @summary section needs to be several lines long to describe what's happening, then it may be necessary to refactor the function into smaller, easier to succinctly describe pieces.

Conclusion

Template-driven documentation helps developers build quality code that may be easier to write, maintain, and extend, thereby saving time, effort, and money.

--

Wes Dean, a Google Apps Certified Deployment Specialist and a Google Apps Trusted Tester, is Principal of KDA Web Technologies, a Google-Centric development firm and a Google Apps Authorized Reseller. To learn how Wes and KDA Web Technologies can help you, go to www.kdaweb.com.