CPSC 124 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. (These conventions will be introduced throughout the course - don't expect all of the following to make sense right away!)

Naming Conventions

All identifiers should have descriptive names of an appropriate length:

Avoid excessively long names and excessively abbreviated names. Long names make your code harder to read and increase the risk of typos, while the more compressed the name, the more likely someone else will have no idea what the abbreviation means.
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 identifiers), you should avoid using multiple names which differ only in case within the same scope. (This helps prevent errors caused by typos.)

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.

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.

Each class declaration should have a comment describing the purpose of the class and identifying the author of the class.

Each method declaration should have a 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.

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

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.

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.