Our industry moves so fast that just to stay on the curve, let alone ahead of it, you need to spend a considerable amount of time reading other peoples code. Whether that be in code reviews, gists, or open source projects, you can glean a lot of invaluable information about new technologies, protocols, and techniques.

As an industry as a whole we need to understand this and write all code, even that which at first is not meant for public consumption, as self-documenting code with comments which detail, to anyone reading it, the why the code is doing what it’s doing.

Self-documenting code is code which follows commonly accepted style conventions, and uses descriptive variable, and function names. As an example, self-documenting code turns this:

function gd(p1, p2) {
  return [p1.x - p2.x, p1.y - p2.y];
}

Into:

function getDifference(point1, point2) {
  var x = point1.x - point2.x;
  var y = point2.y - point2.y;
  return [x, y];
}

It’s much easier to understand what the second function is doing at a glance vs the first.

This function is so trivial many will stop here and continue on. But trivial scripts have a way of becoming more, whether they grow into a project of their own or are copy/pasted into much larger projects where their use may not be as clear.

Lets assume for a moment that this function was copy & pasted into a larger projects utility class. Wouldn’t it be nice if it would automatically be added to the API docs?

/**
  Calculate the difference between the x and y coords of two points.

  @method getDifference
  @param {Object} point1 The first point to compare.
  @param {Object} point2 The second point to compare.
  @return {Array} The difference between the two points in the format [x, y]
*/
function getDifference(point1, point2) {
  var x = point1.x - point2.x;
  var y = point2.y - point2.y;
  return [x, y];
}

This function can now be copy and pasted into any project without any ambiguity about it’s functionality and will automatically be included in the API documentation.

To illustrate the importance of inline comments even with self documenting code. Take the following method from the Juju GUI source.

The Juju GUI has just over 65,000 lines of javascript excluding dependencies and growing fast every day. With so many developers writing code this fast it would be very difficult to understand why things were done the way they were done without the additional 17,000 lines of api comment blocks and inline documentation.

exportYAML: function() {
  var result = this.db.exportDeployer();
  var exportData = jsyaml.dump(result);
  var exportBlob = new Blob([exportData],
             {type: 'text/plain;charset=utf-8'});
  saveAs(exportBlob, 'export.yaml');
},

Using only self-documenting code you would probably be able to figure out that this function extracts some data from a database, converts it into yaml, then saves the blob to disk. Unfortunately this would have taken you at least 4x longer to parse because it doesn’t have any comments. You would also be missing some very important information from a previous bug fix. Now here it is with it’s comments:

/**
  Export the YAML for this environment.

  @method exportYAML
*/
exportYAML: function() {
  var result = this.db.exportDeployer();
  var exportData = jsyaml.dump(result);
  // In order to support Safari 7 the type of this blob needs
  // to be text/plain instead of it's actual type of application/yaml.
  var exportBlob = new Blob([exportData],
      {type: 'text/plain;charset=utf-8'});
  saveAs(exportBlob, 'export.yaml');
},

Without even reading the code you now know what the purpose of this method is which will dramatically reduce time when debugging or adding more features. More importantly however, the why of some of the code is outlined for future-you or another developer who may end up here. Without the comment regarding Safari 7 they very likely could have changed the mime type to application/yaml and introduced a difficult to find bug.

Although these examples were simple I hope I have illustrated the importance of adding comments to your self-documenting code to aid not only future-you but also any other developer who may come by and learn from your work. Thanks for reading! What commenting techniques do you use? Comment below or mention me on twitter @fromanegg.