Fundamentals of Computer Science II (CSC-152 2000S)

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

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.


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.

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.

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.


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''.


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

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.


    // 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


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.

 * A description of the class.
 * @author YOUR NAME HERE
 * @version XXX of DATE
public class XXX {
An introductory comment for the people who have to read your code,
giving an overall structure to the class.

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

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

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

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

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


Spring 1998

Spring 1999

11 August 1999

Monday, 17 January 1999

Disclaimer Often, these pages were created "on the fly" with little, if any, proofreading. Any or all of the information on the pages may be incorrect. Please contact me if you notice errors.

This page may be found at

Source text last modified Mon Jan 17 16:24:56 2000.

This page generated on Mon Jan 17 16:28:19 2000 by Siteweaver. Validate this page's HTML.

Contact our webmaster at