C++ Programming Style

Programs are written for people as well as computers, and a well-designed, well-written, and readable program is easier to write and to debug.

One element of creating a readable program is to follow standard conventions for naming and formatting. The following outlines standard/common C++ conventions, and the conventions we'll be using in this course. Your programs should adhere to the following rules - points will be taken off for not doing so.

Naming Conventions

Filenames should be descriptive, and should end with .h (header files) or .cc (implementation files). Names are generally all lowercase. If a header file is named something.h, the implementation file should generally be named something.cc.

All C++ identifiers must have descriptive names. Some general guidelines: (though not hard-and-fast rules)

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!)
Variable, constant, and class names are typically nouns.
Function names are typically verbs, with names of the form isSomething particularly appropriate for boolean functions. Examples: computeTotal, isEven, isLegalValue.

Identifiers used for different purposes should be easily distinguishable. A common convention (and the one used in this course) is the following:

Variable and function names should start with a lowercase letter, with word breaks indicated by capital letters. Examples: count, totalLength, computeCost. Function calls can be distinguished from variables in code because the name of the function 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 word breaks indicated by capital letters. Examples: Player, BankAccount.
Instance variables should be named like variables (starting with a lowercase letter, word breaks indicated by capital letters), with a trailing underscore. Examples: count_, length_, diceSum_. Note: the book doesn't use this convention, but you should!

Commenting

Each file should contain a comment with your name and a brief description of what is in the file, placed near the top of the file. If the file contains main, this description is a description of what the program does. If the file contains a single class declaration, the description is a description of the class. If the file contains implementations for a bunch of declarations, the description can simply reference the name of the file containing the declarations.

Every class declaration should have a comment describing the purpose of the class immediately before the start of the declaration. (For a file containing a single class declaration, the file comment can replace the class comment.)

Every function prototype and implementation should have a comment describing the purpose of the function, the meaning of each of its parameters, and the meaning of its return value (if any). The comment should also include pre- and postconditions, as appropriate. Information which can be read from the function definition itself should not be repeated in the comment e.g. something like "n is an integer" (when the parameter declaration is int n) is redundant and unnecessary in the comment.

All variables (including instance variables) and constants should have a brief comment describing the purpose of the variable/constant, including any other information relevant to its proper use. These comments are typically short and can occupy a partial line after the declaration; if the comment would wrap onto a third line, then put the comment on line(s) by itself immediately before the declaration.

It can be useful to comment sections of code within a function body, particularly if there are several distinct steps to accomplish the task. Within-function comments should also be used if there is a tricky section of code - perhaps the logic is a bit tricky, something is done in a certain way for some reason, or making a change in one place requires some other change. Comment all of these things to help you organize your thoughts, and to make debugging and maintenance easier.

Whitespace Conventions

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. emacs will auto-indent correctly (incorrect indentations are generally due to syntax errors).

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). emacs will tell you the column number of the cursor so you can keep tabs on how long your lines are (the easiest is just to set your emacs window to 80 columns wide). 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. emacs will often indent things reasonably, but not always. Use your judgement as to what is most readable.

Blank lines should be used to group tightly-related chunks of code and separate less-related parts. Put a blank line between function prototypes and implementations. Within a function, 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.

Named Constants

You should use named constants any time you find yourself using a literal which has some particular meaning. (Which is most of the time.) Some examples of when you wouldn't use a named constant are for values which are part of a mathematical formula but don't have a particular meaning e.g. computing the average of two numbers using (a+b)/2 - the "2" doesn't have any particular meaning, and certainly wouldn't be changed. Not all values in mathematical formulas are exceptions, though - when computing the circumference of a circle, you'd write 2*PI*r, where PI is a named constant with the value 3.1415927... (Actually, there is already a constant defined for π, but that's the idea.)