Coding Guidelines

Introduction

This web page deals with the important issue of what your code looks like when viewed in a window or when printed on a piece of paper. It's easy to focus on getting the code to compile into a working program and to lose track of the fact that programs normally have long lives after they start working. Of course, the programs you write for college courses are not typical in this way, but in the "real world" most of the work on a program comes as bugs are fixed and features are added after the original version of the code starts working. It's critical to write your code so that programmers who come after you will be able to navigate through your code efficiently and to understand its design quicky.

To this end, companies that employ programmers normally have a set of "Programming Standards" that all programmers must adhere to when they write code. There are similar standards for how you write code for CS-101, but instead of calling them "standards," I prefer to call them "guidelines" because I am willing to let you modify them in case you have another style that accomplishes the same goals as the rules given here.

I have an ulterior motive here, by the way. If you write your code following these guidelines, I will have a lot easier time grading your programs! I will be able to locate the code for your classes and methods quickly, I'll be able to understand the design of your methods easily, and I'll be able to locate and evaluate errors most readily. So, although we are working in an academic environment, there is a good parallel between your writing clear code for me to grade and your writing clear code for other programmers to maintain in the real world.

Tabs and Indentation

The following are rules that you must follow when you write your code:

Files and Classes

Put each class or interface that you write into a separate .java file, even if the class is not public. This modular design will make it easier to maintain your code, because there is less code to deal with at a time.

The exceptions to this rule are anonymous and other inner classes. Since they are defined inside another class, they pretty obviously can't be defined in separate files.

Commenting Your Code

It's a good idea to put the name of each source file in a comment at the very beginning of the file. That way, you can easily tell what file you are editing as soon as it appears on the screen of your text editor.

Put a block of comments just before each class, interface, or method in each source file. These comments should start with a line that tells what is being defined, such as:

    //  Class Xyx
or    
    //  Interface Abc
or
    //  Method abc()

Then put a comment line with a row of dashes, or equal signs, or asterisks, or whatever you like to make the comment block easy to find when scrolling through the file. Don't use this type of comment line elsewhere; the idea is to show where a class, interface, or method begins, and nothing else.

Next put a "javadoc" comment block. (see [ below ] for information on running javadoc.) A javadoc comment block starts with /** (note there must be at least two asterisks) and ends with */. Asterisks at the beginning of lines inside a javadoc comment block are ignored, but everything else will be used by javadoc to generate HTML documentation for your code.

The first thing inside a javadoc block has to be a sentence (capitalize the first word and end with a period) that tells what the class, interface, or method does. The style for this sentence is to start with a present-tense verb with the name of the class, interface, or method as the implicit subject. For example, instead of saying "Interface Abc defines the methods that must ...", say "Defines the methods that must ...". There can be more than one sentence in the description, but early versions of javadoc limited the description to just one, and it's better to make your description brief rather than wordy.

After the description, use javadoc "tags" to tell about specific features of the class, interface, or method. A javadoc tag starts with an @ character followed immediately by the name of the tag. We will use just three of these javadoc tags for this course:

You can see a file that is documented according to these guidelines [ here ]

Running javadoc

The javadoc command generates HTML documentation pages for your programs by extracting information from the comments in your code. The output of the javadoc command changed somewhat between JDK versions 1.1.x and 1.2. Most notably, the earlier version used graphical images (GIFs) as labels for the various parts of the generated pages, making it necessary to copy those images along with the web pages in order to view the documentation properly. The later version produces a self-contained set of pages.

To run javadoc, first create a directory under your project directory to hold the HTML files produced by javadoc. If you named this directory docs, the command to generate the documentation for all the .java files in your project directory would be

    javadoc -author -d docs *.java
You need the -author switch to get javadoc to process your @author tags. They are ignored by default. The -d switch is immediately followed by the name of the directory where you want to save the HTML (and other) files generated by running the javadoc command. Finally, *.java uses the asterisk wildcard to generate a list of all files that have names ending with .java.

You can view the files generated by javadoc by using a web browser, even though you are not connected to the Internet. Use the browser's File menu, select open, select the directory where you saved the HTML output, and select the file named index.html to start browsing your documentation!

You can click on the following link now to look at the web pages generated by the Java 2 version of javadoc for the sample code given above:

Note that you are not to submit javadoc output to me. I will generate it myself when I grade your project.