CPSC 225, Spring 2002
Style Rules for C++ Programming


COMPUTER PROGRAMS should be written so that they can be read, understood, and modified by human readers. Programming style is important, and all programs in this course will be graded for style as well as for correctness. This page lists the basic programming style rules that you should keep in mind as you write your programs.

The Main Rule 0.   A program should be readable. All the other rules on this page can be overridden by this primary rule. Your programs should display good taste, which you can generally acquire only by paying attention to the practices of other, expert programmers.
Comments 1.  Every program should start with a comment that includes: a statement of the purpose of the program; a description of the input and output of the program, including the style of interaction and the meaning of command line arguments, if any; notes about any restrictions on the program, such as inputs that it cannot handle; name of the programmer, date, and, if appropriate, a version number and a list of modifications made to the original version.
2.  Every variable that has a non-trivial role in the program should have a comment that explains its purpose. This generally does not include for-loop variables and other utility variables, but it does include most other variables.
3.  Every function should have a comment explaining what it does. This should include any conditions that must hold when it is called, such as restrictions on the acceptable values of its parameters. (These are called the "preconditions" of the function.) The purpose of each parameter should be clearly documented. If the function relies on or makes changes to global variables, this should be documented.
4.  Every class definition should have a comment, explaining what is represented by an object belonging to the class.
5.  Comments can be included in the body of a subroutine when they are needed to explain the logic of the code. In general, well-written code needs few comments.
6.  Comments should never be used to explain the C++ language. A comment such as "declare an int variable named x" or "increment the variable ct" is worse than useless. Assume that your reader knows C++. (Note that such comments are sometimes used in programming textbooks or on the blackboard, but never in real programs.)
Formatting 7.  Use indentation to display the structure of your program. The body of a function definition should be indented. When a statement is nested inside another statement, it should be indented one additional level. Each level of indentation should be two, three, or four spaces. Don't use tabs for indentation, since you can't be sure how they will appear when printed or when viewed in a different editor.
8.  An ending "}" should be on a line by itself. The opening "{" can be at the end of a line, or it can be placed on a line by itself so that it lines up with the matching "}".
9.  Don't put more that one statement on a line.
10.  Avoid very long lines. In general, lines should not be longer than 80 characters. Longer statements should be broken up over several lines.
11.  Avoid very deep nesting of statements. If you find yourself using more than two or three levels of nesting, think about defining some functions in order to break up your code into more manageable chunks.
12.  Blank spaces and blank lines can make a program easier to read. Always put some blank lines between function definitions. Leave spaces around operators such as =, ==, !=, and so on.
Naming 13.  Use meaningful names for your variables, functions, and classes.
14.  Use a consistent style of capitalization. For example: Begin variable and function names with lower case, and begin class names with upper case. Capitalize words that begin in the middle of an identifier. (For example: interestRate.) Use all upper case for the names of constants, with words separated by underscores. (Many C++ libraries, however, simply use only lower case letters in all identifiers.)
15.  Use "const" to declare named constants to represent constant data. Consider using "enum" to create several related integer constants.
Functions 16.  A function should have a clear, single, identifiable task.
17.  Avoid using global variables in functions. In general, functions should use parameters and return values for communication with the rest of the program.
18.  An individual function should not be too long. In general, a function should not be longer than one printed page.
Classes 19.  A class should represent a clear, single, identifiable concept.
20.  Data members should, in general, be declared to be private. Member functions can be provided to access and manipulate the private data members. (Use "struct" instead of "class" for simple data structures that contain only public data members.)
21.  A non-trivial class should generally be declared in its own ".h" file and defined in its own ".cc" file. The name of the files should be the same as the name of the class.
David Eck, 4 January 2002