6.170 / Spring 2001 / Java Style Guide

Handout S1

• Overview
• Descriptive names
• Consistent indentation
• Informative comments

Overview

Many aspects of code help make it readable. Some of the most important are descriptive names, consistent indentation, and informative comments.

In 6.170 we do not specify a detailed coding style that you must follow. However we expect your code to be clear and easy to understand. This handout provides overall guidelines within which you should develop your own effective coding style.

Descriptive names

A common convention that we recommend you follow is to capitalize names of classes, but start variable and package names with a lower case letter. There are other common conventions, such as naming constants using all uppercase letters; we do not require you to follow any particular conventions, but you should choose those that you find helpful and follow them consistently.

Consistent indentation

Emacs provides an autoindent mode. You should use it to format your code as you type it, and reformat it after you have changed it. You can also use grind to format your code nicely for printing even if the source file is not well indented.

Informative comments

    i++;    // increment i     THIS IS A USELESS COMMENT

• Enable the reader to avoid reading some code. The following comment saves the reader the effort of figuring out the effect of some complicated formulas, and states the programmer's intention so the formulas can be checked later on.

  // compute the standard deviation of list elements that are
  // less than the cutoff value
  for (int i=0; i<n; i++) {
      //...
  }

  An important application of this type of comment is to document the arguments and return values of functions so clients need not read the implementation to understand how to use the function.
   
• Explain an obscure step or algorithm. This is especially important when the effects of some step are not immediately obvious in the code itself. You should explain tricky algorithms, operations with side effects, magic numbers in the code, etc.

  // Signal that a new transfer request is complete and ready
  // to process. The manager thread will begin the disk transfer
  // the next time it wakes up and notices that this variable has changed.
  buffer_manager.active_requests ++;

• Record assumptions. Under what assumptions does a piece of code work properly?

  // The buffer contains at least one character.
  // If the buffer is empty, the interrupt handler returns without
  // invoking this function.
  c = buffer.get_next_character();

• Record limitations and incomplete code. Frequently the first version of code is not complete; it is important to record which code is known to be incorrect. If you run out of time on an assignment and turn in a program that does not function correctly on all inputs, we will expect your code to show that you understand its limitations.

  if (n > 0) {
      average = sum / n;
  } else {
      // XXX need to use decayed average from previous iteration.
      // For now, just use an arbitrary value.
      average = 15;
  }

• Don't write code first and then comment it -- comment it as you go along. You are unlikely to go back and do it later.
• We do not require you to write comments on every program object as is done in some software engineering courses. However, your grade depends substantially on the clarity of your code, and some piece of the program that seems clear to you may not be clear to the reader. Therefore, it may be to your advantage to add explanatory comments to all classes, fields, and methods.