CPSC 424 Programming Standards

While the emphasis in this course is on the concepts of computer graphics, programs should still be written in an organized and readable way. (After all, this also helps you organize your thoughts, increasing the likelihood of writing a correct program in the first place and making it easier to debug otherwise.)

You are free to follow any reasonable convention for naming and formatting as long as you do so consistently; the conventions outlined below are the ones used by the provided code and are thus recommended.

Naming Conventions

Unlike Java, C++ does not dictate filenames. Some guidelines:

Filenames should end with .h (header files) or .cc (implementation files).
Choose descriptive names. For a file containing a class declaration (and possibly some other related declarations), use the class name as the filename.
Use the same base name for related header and implementation files e.g. something.h and something.cc.
Use only lowercase letters in the filename.

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 C++ 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:

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_.

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.

Files

Every file should have a comment at the beginning of the file identifying the author of the file.

The file containing the main program and any header file containing more than a single class declaration should also have comments describing the purpose of the file. File comments can be omitted from other implementation files if those files accompany a header file.

Classes

Each class declaration should have comment describing the purpose of the class. For files containing only a single class declaration, this comment can take the place of the comment describing the purpose of the file.

Class Methods

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/Constants

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). Short descriptions can occupy a partial line after the declaration, while longer descriptions should go on separate line(s) immediately before the declaration.

Internal Comments

Internal comments refer to comments inside a class method.

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 C++ 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.