Java Style Guide

This document is still under development. Any suggestions would be appreciated.

Programming, like writing, provides you some freedom to express the same concept in many different ways. Just as each writer develops his or her own personal style, so do programmers. Important aspects of programming style include

• the choise and capitalization of names (variables, function names, class names);
• the use of whitespace (carriage returns, indents) in coding;
• the ordering of components that may be presented in different orders; and
• the type and number of comments you use.

I expect you to follow some basic stylistic conventions in my class. While you will eventually develop your own style, few of you are experienced enough programs to make sufficiently informed decisions. In addition, a uniform style helps us discuss and share code. I will strive to use the same style, but may violate it ocassionally. If you use emacs as your editor, it will automatically enforce some of these rules.

Names

A typical program requires a significant amount of naming of variables, fields, functions, and classes. Strive for informative and distinguishable names. You should rarely use single-letter names (except, possibly, for loop counters). At the same time, you need not go overboard on the length of your names. For most purposes, five to ten characters suffice.

Sun (the developers of Java) recommends a particular capitalization style to help you distinguish the different things that you can name.

• Class names should begin with an uppercase letter and have mixed case. For example, TimeZone and InputReader.
• Function names (method names) should begin with a lowercase letter and have mixed case when appropriate. For example, readInteger of getDefault.
• Variable names (field names) should not include uppercase letters. They may include underscores to separate words.
• Constants (or variables that act like constants) should be in all capital letters. They may also use underscores and digits. For example, TESTING.

White Space

Java is whitespace-insensitive (at least in most cases). You can put as few or as many spaces, tabs, and carriage returns as you want in your programs. Hence, you should use whitespace to make your programs more readable, modifiable, and debugable.

• Include a blank line before each new function and between indpendent sections of a function. This helps the reader quickly skip between parts.
• For nested code (most often surrounded by curly braces), indent the nested code by two or three spaces (I use two; many people use three; emacs seems to use 3).
• Don't put anything on the same line after an opening curly brace. Doing so makes it difficult to insert new code at the beginning of that block.
• Don't put anything on the same line before a closing curly brace. Doing so makes it difficult to insert new code before the end of the block.
• Some people prefer to put opening curly brace on a line by themselves. You'll see this style in Java Plus Data Structures. Much of the time, I prefer to put the opening curly brace after the thing that is being opened.
• Align your curly braces (this should be automatic if you indent according to my rules above, but this is a reminder). This makes it easier to understand the control flow of your program.
• When Java forces you to include curly braces around one command, you can put them on one line, as in

  try { line = input.readLine(); }
  catch (Exception e) { line = ""; }
  

Long Lines

Long lines of code are often hard to read, particularly when you print them out on a printer that only prints 80 columns. (Sometimes the extra text is lost; sometimes it's wrapped to the next line.) Hence, you will often need to reformat or break long lines. Try to indent the continued line in such a way that makes the relationships clear. For example, you should indent arguments so that they match the open parenthesis for a method.

Comments

If people are to read your class (and yes, people will sometimes need to read your classes), you must provide comments to help them get through the morass of Java.

An introductory javadoc class comment describes the purpose of your class and may give examples of usage.

An introductory programmer's comment follows the Javadoc comment, and gives details of the implementation for those who need it (primarily those who will want to extend or maintain your code).

Each field and method must be preceded by a short javadoc comment that describes their use. I recommend taht your comment include the six P's (summarized below).

Within a method, you should provide short, natural-language comments that describe what you intend to do with your code in each ``step'' (a step need not be a line of code; some steps involve multiple lines).

If you use particularly tricky or confusing code (and yes, you probably know which pieces are tricky or confusing), please include an explanation of what's going on.

The Six P's

When you design and document methods, you need to think about a variety of things. Last semester, students found it useful to use what we ended up calling ``the six Ps''.

• The purpose of the method.
• The parameters of the method.
• The preconditions of the method. That is, requirements that must be met in order for the method to succeed.
• The postconditions of the method. That is, what you can guarantee will hold after the method finishes successfully.
• Potential problems that may arise. In Java, you may throw exceptions when problems arise.
• The type and value of results the method produces. (The return value and the return type. It took a little effort to fit this round peg into the square hole of ``begins with p''.)

Ordering

It is helpful to the reader if you order the code within your classes in a uniform way. For example, you might separate your program into

• Constants
• Fields
• Constructors
• Public methods, for external use
  • Methods that modify the object
  • Methods that just extract information
• Helper methods, for internal use

Most readers also find it useful if you provide clear divisions between the different sections.

This is not the only way to segment your classes. For example, if your class contains a large number of methods, you may want to group them according to functionality.

While some people will read your code in electronic form, others will need to read a printed copy. It helps if you alphabetize the methods or provide a "table of contents" at the beginning.

Examples

    // Step through the list of people, printing out all the students.
    for (int i = 0; i < REPETITIONS; ++i) 
      {
        // If person i is a student then ...
        if (people[i].getRole().equals("student")) 
          {
            // Print out the name of person i.
            System.out.println(people[i].getName() + " is a student");
          } // if
      } // for

Template

Here is a template you might use as you begin to write your classes. It is not the only possible structure, but it is a beginning.

/*
An introductory comment for the people who have to read your code,
giving an overall structure to the class.
*/
package XXX;
import XXX;

/**
 * A description of the class.
 *
 * @author YOUR NAME HERE
 * @version XXX of DATE
 */
public class XXX {

   // +--------+--------------------------------------------------
   // | Fields |
   // +--------+

   // +--------------+--------------------------------------------
   // | Constructors |
   // +--------------+

   // +--------------+--------------------------------------------
   // | Transformers |
   // +--------------+

   // +-----------+-----------------------------------------------
   // | Observers |
   // +-----------+

   // +----------------+------------------------------------------
   // | Helper Methods |
   // +----------------+
} // class XXX