Fundamentals of Computer Science II (CSC-152 99F)


Java Style Guide

This document is still under development.

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.

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.

Whitespace

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.

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.

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.

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

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.

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

   // +----------------+------------------------------------------
   // | Public Methods |
   // +----------------+

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

History

Spring 1998

Spring 1999

11 August 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 http://www.math.grin.edu/~rebelsky/Courses/CS152/99F/Handouts/java-styleguide.html

Source text last modified Wed Aug 11 11:01:09 1999.

This page generated on Sat Aug 21 22:43:55 1999 by Siteweaver. Validate this page's HTML.

Contact our webmaster at rebelsky@grinnell.edu