CPSC 329 Programming Standards

There is much more to a good program than just having it run correctly - while correct functioning is critical, it is also important to create a well-organized, well-documented, and easy-to-understand program. Why? For starters, it is much easier to create a correctly-functioning program and to verify its correctness if the program is organized and its logic is clear. Furthermore, the initial development is only a relatively small portion of the life cycle of most real software - fixing bugs and adding new features may go on well after the initial product is shipped, and may be done by people not involved in the original development.

One aspect of creating readable programs is to follow standard conventions for naming and formatting. There are a number of variations and you will see different styles used in different places. The following outlines the conventions we'll be using in this course, and the conventions you should use in any programs you hand in.

Naming Conventions

All identifiers should have descriptive names of an appropriate length:

Avoid excessively long and excessively abbreviated names.
One-letter variable names are rarely descriptive, though some common exceptions include using i, j, and k for loop counters, n for the number of things, and x, y, and z for coordinates of points. (But don't feel obliged to use these names if you can think of better ones!)
When loop counters can be named descriptively, they should be. (e.g. name the counter after what is being counted)
Use nouns or short noun phrases for variable, constant, and class names. Examples: Dice, BinaryTree, numSpaces, MAX_WIDTH
Use verbs or short verb phrases for method names. Methods which return boolean values should generally start with is. Examples: computeTotal, sort, isLegalValue
Getters and setters should have names beginning with get or set, with the exception of boolean-valued getters which should be named starting with is. Examples: getX, setName, isVisible
While Java is case-sensitive (i.e. sum and Sum are different identifies), you should avoid using multiple names within the same scope which differ only in case.

Identifiers used for different purposes should be easily distinguishable. In this course, the following convention is used/expected:

Variable and method names should start with a lowercase letter, with separate words indicated by capital letters. Examples: count, totalLength, computeCost. Method calls can be distinguished from variables in code because the name of the method in the call is always followed by parentheses.
Named constants should be all caps, with underscores to separate words. Examples: WIDTH, MAX_ENTRIES.
Class names should start with a capital letter, with new words indicated by capital letters. Examples: Player, BankAccount.
Instance variables are named like variables (starting with a lowercase letter, new words indicated by capital letters), with a trailing underscore. Examples: count_, length_, diceSum_. Note: this convention is not used by the book, but you should use it.

Eclipse can be configured to handle some of these naming conventions automatically.

Commenting

Comments are for the human reader, and provide important information about how to use and understand your code. Comments should not repeat information readily apparent from the code (e.g. commenting the declaration int n as "n is an integer" is redundant and unnecessary), but should instead provide additional information about the meaning and usage of the code.

Eclipse can be configured to auto-generate comment skeletons for classes and methods. Type the method header first, then position the cursor before the header and type the leading /** of a Javadoc comment - when you press enter, Eclipse will produce a skeleton for the comment. If you are using Eclipse to auto-generate code, make sure the "generate comments" box is checked in the dialog box. Note: Eclipse's auto-generated comments are not complete! - but they do give you a start.

Javadoc

Javadoc is a tool for automatically generating API documentation from the source code. It gathers its information from the class, method, and instance variable/comment declarations in the code itself as well as from specially-formatted comments.

Javadoc comments are useful even if you don't plan to run javadoc because the structure required for javadoc provides a nice organization for the information that should be included in the comment anyway.

For a full description of javadoc, see How to Write Doc Comments for the Javadoc Tool, or skip straight to the example which illustrates the basic format and key features of javadoc comments.

Commenting Rules

Classes

Each class declaration should have a javadoc comment describing the purpose of the class and identifying the author of the class. Use the @author tag to identify the author.

Class Methods

Each method declaration should have a javadoc comment describing the purpose of the method, its pre- and postconditions, the meaning of each of its parameters, the meaning of its return value (if any), the conditions under which exceptions are thrown (if any), and any other information relevant to someone using the method. Use the @param tag to describe parameters, the @return tag to describe the return value, and the @exception tag to describe any exceptions thrown.

Instance Variables/Constants

Instance variables and constants should have a javadoc comment describing the purpose of the variable/constant, including any other information relevant to its proper use (e.g. limits on value or units).

Internal Comments

Internal comments refer to comments inside a class method. Javadoc does not process internal comments so you may use standard single-line (//) or multline (/* */) commenting styles, and you do not need to include any special tags.

Local variables and constants should have a brief comment describing their purpose and any other information relevant to their proper use (e.g. limits on value or units); short descriptions can occupy a partial line after the declaration, while longer descriptions should go on separate line(s) immediately before the declaration.

Individual blocks of code within a larger method should have a brief description of their purpose. These comments typically come from the pseudocode steps of the algorithm being implemented, or might be added as a note to draw attention to a tricky or important point that isn't immediately obvious from the code itself (e.g. something is done in a certain way for some reason, or making a change in one place requires some other change somewhere else).

Whitespace

Whitespace is largely ignored by the Java compiler, but it is crucial for the human reader of the program. Eclipse can be configured to auto-format your code reasonably well, so there is no excuse for turning in programs which don't make appropriate and consistent use of whitespace. (Use ctrl-shift-F or Source->Format to reformat the current file.)

Indentation should be used to indicate the block level of each statement - the bodies of classes, functions, conditionals, loops, and block statements are indented one additional level beyond the current indentation.

Semi-colons (;) and both open and close curly brackets ({ and }) should generally be followed by a line break. One exception is that it is acceptable to put a single short statement on the same line as the curly brackets:

if ( x > 0 ) { return 1; }
else {
  System.out.println("This is not quite right!");
  return -1;
}

Line breaks should be used to split up long statements so that no text goes beyond 80 columns wide (the standard width that fits on one line of a printed page). Line breaks can go anywhere except in the middle of an identifier, keyword, multi-symbol operator (like between the < and = in <=), or string. To decide on a good place, try to avoid breaking up chunks of the statement that are closely related. After an operator or a comma are often good places. When you break a statement into multiple lines, use indentation to help the reader follow the statement. The indentation should generally be used to line up text with similar text on the previous line of the statement, though there are exceptions to this when it would result in very large indentations.

Use blank lines to group tightly-related chunks of code and separate less-related parts. Within a method, blank lines can be used to group different parts of the function's task - e.g. put a blank line between a set of variable declarations and the code that uses them, or between the code that reads the user's input and the code that processes it. There aren't hard and fast rules, but remember that the goal is to help the reader understand the structure of the program.