CPSC 124 Introduction to Programming Fall 2010

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:

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


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.


Valid HTML 4.01!