Program elements

Every program should have the following:

Header

Every one of your program files should have this comment at the very top of the file. This is helpful to you and me. For instance, if you look back at a source code file several weeks (or months or years) after you've written it, this header will provide you with the context of the program.

(Back to top)

Comments

You should use comments in your code to ensure it is understandable. It is important that larger blocks of code, even if they are easy to follow, are preceded by a comment summarizing the goal of the following code. For lines or small blocks of code that are confusing, it is helpful to have comments that make clear the confusing bits. Comments should not describe the code itself, but rather the goal of the code. Here's an example of good commenting and bad commenting:

Bad commenting 

// Assign 'Alice' to a variable named 'name'.
string name = "Alice";

Good 

// Alice is the name of the heroine in our adventure game.
string name = "Alice";

One common style for function comments is JavaDoc format (which can also be used with the Doxygen documentation generator). This style has annotations that allow an external program to be run over the source code to build documentation pages in HTML. The basic format is:

You should have one @param annotation per incoming parameter and they should be listed in the order specified in the function signature. The @return annotation should occur last and should only be included if the function returns a value; i.e., do not include it if the return type is void.

Comment checklist

(Back to top)

Appropriate Identifier Naming

Identifiers are the names you give to elements like constants, variables, functions, and classes, and they should make clear what the element is and does. Identifiers should be concise, consistent, and readable. What does that mean?

Concise

Identifiers should be as short as possible while still clearly conveying the purpose of the underlying element.

Consistent

Consistency means that multiple identifiers referring to relative levels of concepts should show that relativity in their names. For example, if a program has variables for a customer's first and last name, well named identifiers for these two variables are: firstName and lastName; poorly named identifiers are: name and lastName. In the poorly named case, it's unclear looking at name to know how it differs from lastName (is it the first name, whole name, middle name, nick name, ...?).

Readable

You should avoid abbreviations, uncommon acronyms, and single characters (unless appropriate, such as using x in a math function or i in a for loop). Studies have shown that expanded identifiers make it easier to comprehend code blocks. In addition, use clear delimiters between words within an identifier, e.g., under_scores or camelCasing. The identifier maxoveralscore is much harder to read than maxOverallScore or max_overall_score.

(Back to top)

Good use of white space

White space includes brace placement, spacing between lines, and indentation. The convention we use in this class is to always place curly braces on their own line, indented to the level of the code outside of the curly braces. Inside of the curly braces, everything should be indented one tab more. I usually use four spaces per tab. Code that is aligned is significantly easier to read.

Also, add in blank lines between chunks of strongly related code. In the good examples below, I put a blank line between logical segments of code. The rule of thumb I use is, one blank line above every comment.

Good

Or, with the curly braces removed because the block only has one line:

Bad (Back to top)

Line width

A standard CLI is 80 characters wide. Even though I do most of my editing in a text editor rather than via a CLI, I still use 80 characters as my limit. In Sublime Text, it's easy to set up a ruler at 80 characters. This lets you see how close you are to hitting the limit. Go to View→Ruler→80. Remember that you can spread long C++ statements across multiple lines!