Writing code comments

When you are embedded deep in the flow of coding, adding comments can feel like a penalty on your efficiency. "My code is so obvious that it doesn't need any comments," says every engineer to themselves. "Your code needs better comments," responds every engineer who reads your code.

The main audiences for your code comments are as follows:

  • The engineers maintaining your source code. This audience needs to understand how your code works.
  • The engineers using your APIs. This audience needs to know how to instantiate classes and call methods.

In most situations, a language style guide defines the mechanics of comments. For example, a style guide tells you where you must place comments and how to define parameters in order to build an automated reference guide. This unit, however, goes beyond mechanics, aiming to help you write genuinely helpful comments.

Lesson 1: Good commenting means good writing

As Google's Python Style Guide notes, "it is easier to read well-written comments than badly written ones." To create well-written comments, apply the lessons learned in Technical Writing One. For example:

  • Write in active voice.
  • Prefer shorter sentences to longer ones.
  • Pick specific common words over vague or obscure words.
  • Craft an excellent first sentence in every paragraph.
  • Consider using lists instead of prose.
  • Avoid slang.

Doc comments for users

Write documentation comments for your users. They just want to know the details of what a class, function, or parameter does for them. Be brief.

Implementation comments for maintainers

Maintainers (including you) may need to know more detail about how you did something, particularly in non-obvious or clever bits of code. But don't over-comment: if the code speaks for itself, be quiet.

Exercise: doc comments

Write a documentation comment for the following function. Also, add, remove, or change implementation comments as you see fit.

function shuffle (array) {

  var currentIndex = array.length;
  // Return the array if the current index is 0.
  if (currentIndex === 0) return array;

  // Decrement currentIndex and use a while loop to work through the array.
  while (--currentIndex) {
    // Pick a random remaining element.
    var randomIndex = Math.floor(Math.random() * (currentIndex + 1));

    // Swap it with current element.
    var tempVal = array[currentIndex];
    array[currentIndex] = array[randomIndex];
    array[randomIndex] = tempVal;
  }
  return array;
}
Possible answer (additions/changes in bold or strikeout):
/**
 * Shuffles the given array in place and returns it.
 * @param array {array of integers} the unshuffled array. Cannot be null.
 * @return array {array of integers} the shuffled array.
 */
function shuffle (array) {

  var currentIndex = array.length;
  // Return the array if the current index is 0.
  // No need to shuffle an array with zero elements.
  if (currentIndex === 0) return array;

  // Decrement currentIndex and use a while loop to work through the array.
  // Work down from the top (highest index) of the array.
  while (--currentIndex) {
    // Pick a random remaining element.
    var randomIndex = Math.floor(Math.random() * (currentIndex + 1));

    // Swap it with current element.
    var tempVal = array[currentIndex];
    array[currentIndex] = array[randomIndex];
    array[randomIndex] = tempVal;
  }
  return array;
}