Most of the 7 style categories are made up of specific styles which are explained in detail under each category and are summarized as bullet points at the end of this style guide. Grading will be done independently for each style within a style category.

1. Header comments
   • Are all required names and descriptions listed
2. Format
   • Are the statements on their own lines?
   • Are if-statement and while-statements K&R style or Stroustrup style?
   • Are sub‐statements consistently indented and using the same number of spaces (usually 3 or 4)?
   • Is there exactly one space between operators (e.g., =, <, >, etc.) and other appropriate items?
   • Are if‐else-statements Stroustrup style?
   • Are sub-braces always used even if there is only a single sub-statement?
   • Are line lengths within 80 characters?
3. Test Cases
   • Are there diverse original test cases demonstrating unique tests?
   • Do the test cases cover different aspects of functionality?
   • Have corner cases been considered in the test cases?
   • Are test cases documented with justification and expected output?
4. Variables and Constants
   • Are the variables camelCase (with the first letter lowercase) or with delimiter-separated words that use lowercase letters and underscores as delimiters?
   • Are the constants all caps with underscores between words?
   • Are variables and constants initialized when they are declared?
   • Are variables and constants declared at the appropriate place in the program?
   • Is the variable naming convention consistent?
5. Magic Numbers
   • Are all numbers in the code constants or fit reasonable exceptions?
6. Functions and Methods
   • Are the names camelCase (with the first letter lowercase) or with delimiter-separated words that use lowercase letters and underscores as delimiters?
   • Are the parameter names descriptive?
   • Do the functions or methods only do task?
   • Are functions and methods used to avoid duplicate code?
   • Does the visibility (i.e., global, static, public, private, protected, etc.) make sense?
   • Are parameters declared as const-references where appropriate to avoid needless copying?
7. Objects and Classes
   • Are class names camelCase (with the first letter uppercase for class names)?
   • Are the names descriptive?
   • Does each class have a default constructor?
   • Are methods that do not mutate state declared as const?
   • Do methods have the appropriate visibility (e.g., private, pubic, or protected)?
8. Miscellaneous
   • Is the code self-documenting only including comments where needed?
   • Is any use of a global variable justified and appropriate?
   • Is any use of a goto-statement justified and appropriate?
   • Does the code use coot-statements and ends-statements?
   • Does the main method function return 0 in the absence of an error and non-zero otherwise?

At the very top of each file, there must be a complement block with the following information:

1. Your name, class section number, and learning suite e‐mail
2. A description of the purpose of the code
3. A description of the inputs needed (if any)
4. A description of the output (if any)

Here is an example of a reasonable header

/*
Sandra Dean, Section 3, Sandra@hotmail.com
Purpose: Calculate how many pizzas of various sizes a user should buy Input:
Number of people eating
Amount of tip Output:
Number of large, medium, and small pizzas necessary Total area of pizza for everyone
Area of pizza per person
Total cost including tip
*/

At the end of the header comments for the main program file, include test cases or indicate where the test cases are located. Labs 8‐10 have multiple files. For files other than main you should also have header comments. However, in these cases the comments just need to briefly describe the purpose of the file.

This section is focused on how your code looks, not on its functionality. Although sloppy code may accomplish the same thing neat code does, it is much harder to read, debug, and maintain. Furthermore, sloppy code has a defect rate (i.e., a greater likelihood and density of bugs). The goal of format is to write code that is easy to work with since it likely that others will be having to use it (especially in industry).

Do

x = 25;
y = x + 1; 
if (x == 5) {
   y = 14; 
}

And Don't

x = 25; y = x + 1; 
if (x == 5) { y = 14;}

There are widely‐adhered to rules regarding brace placement. Either K&R style or Stroustrup style style is acceptable. For K&R style, branches, loops, and classes, opening braces appear at the end of the item’s line; closing braces appear under the item’s start. Functions however have the opening brace on the next line at the same indentation level of the line. For Stroustrup style, it does not use the cuddled-else.

// K&R Style
void who() 
{
   if (x == 0) {
      ...
   } else {
      ... 
   }
}
 
// Stroustrup
void who() 
{
   if (x == 0) {
      ...
   } 
   else {
      ... 
   }
}

Sub‐statements are indented 3 or 4 spaces from their parent statements. Be consistent in whatever is chosen. One way to do this is to use the tab key in the system you use to write your code as most editors will convert the tabs to spaces Do

if (a < b) {
   x = 25;
   y = x + 1;
}

And don't

if (a < b) {
 x = 25;
   y = x +1;
}
if (a < b) { 
x = 25;
}

Operators are separated by one space (not less or more). Separate keywords with one space as well.

Do

x = y + 3;
if (x > y) {
   ...
}

And don't

x=y + 3;
if(x>y){
   ...
}

Even if there is a single sub-statement, curly braces are required. Do

if (a < b) {
   x = 25;
}

And don't

if (a < b)
   x = 25;

Many a weekend has been blown by ignoring this style rule as it leads to errors (often).

80 characters is the old rule for how many characters can print on a single line. More practically, code is more readable when lines are kept short (and all visible on the screen). One long line can usually be broken up into several smaller ones. If a line is just inherently long, use newlines with indentation to improve readability. Do

cout << "This is a string" << endl;
cout << "This is a second string" << endl; 
cout << "This is a third string" << endl;

And don't

cout << "This is a string" << endl << "This is a second string" << endl << "This is a third string" << endl;

Group the code into common segments using newlines. For example, if a method consists of three distinct steps, then separate each step with a newline. Whitespace can be very effective in helping the code be readable.

Test cases strive to ensure correctness in the code. Simple situations should be covered, but more importantly, obscure and less common cases need to be considered. For example, when testing a video game, testers do not simply play the game through; instead, they do obscure things such as walk into walls and corners, jump up trees, and cross invisible boundaries. Their goal is to break the code : they want to find every possible error in the game, expose them, and then fix them. Tests should consider where your code could fail, and then test those areas.

Test cases should include the expected output, and where possible, assert that the program output matches the expected output. It is strongly encouraged, where possible, to write test cases first, with the expected output, before writing the program itself. Also, once the program is written, write additional test cases knowing how the program is written. In other words, use the understanding of the program to break the program with unexpected inputs.

Test cases should run automatically. A program should be able to compile or run in test mode. Test mode runs all tests automatically and reports the test results. Failing tests can then be debugged using the test input.

Variable and parameter names must be written in camelCase with the first letter being lowercase or delimiter-separated words that use lower case letters and underscores as delimiters. Which ever style is adopted, be consistent through all the code. Do

//Always use camelCase
int numPeople;

or

// Always use underscore delimited
int num_people;

And don't

int NumPeople;

or

int numpeople;

or

int numPeople;
int num_cars;

Variable names should be descriptive and useful. For code with options, variable names such as “firstOption”, “first”, “seven”, or “optionA” are not useful; to make sense of these names other knowledge is required, which is not discernible from the name alone. Instead, give variables names meaning such as “averageClassSize” or “exitOption”. Furthermore, avoid using abbreviations and single‐letter variables; a good practice is to think, Would a random person understand what this variable name represents? Variable names are usually at least two words, except in exceptional cases like indexes (e.g. i, j, or k). Do

int numberOfBoxes;
char userName;

And don't

int boxes; 
int b;
char k;
char usrKey;

Use const for any variable whose value will not be changing. Constants are written in upper case and underscore delimited (and are usually at least two words, except in a few obvious cases like PI, etc.). Do

const int MAXIMUM_WEIGHT = 300;

And don't

const int MAXIUMUMWEIGHT = 300; 
const int maximumWeight = 300;
const int MAXIMUM = 300;

Always initialize a variable or constant (meaning give it value) when it is first declared.

int numPizzas = 0; 
char userKey = ‘‐’;

And don't

int numPizzas; 
char userKey;

In some cases it will not seem necessary to initialize the variable; however, for example, by initializing numbers to 0 you can avoid potential difficult bugs when code is mistakenly using an uninitialized variable which contains an unpredictable value. Some types, like “char”, may not have a canonical agreed upon initial value, but by choosing a consistent initial value, such difficult bugs coming from unpredictable values are avoided. Some types, like strings, are automatically initialized; thus, these do not need initialization.

Variables are declared at the top of their enclosing scope (including main) except iterator variables in for loops; for example:

for (int i = 0; i < MAX_PIZZAS; ++i) {
   ...
}

Declare iterator variables in for-statements as shown above except in cases where the iterator variable is needed after the loop. See the functions section below for variable and constant style when there are multiple functions.

Literals other than 0 and 1 should rarely occur in the body of code. Use constants or variables to replace such magic numbers. Using constants has two important advantages. First, they make the code easier to read. Your code should read more like English prose with numbers replaced by descriptively named constants. And second, in cases where the programmer wants to later change the value of a constant, it need only be changed in one place at the declaration, and it will be updated in all places throughout the program.

For example, you would never have a line of code in you program like:

totalCost = numberOfLargePizzas * 14.88;


The literal 14.88 is a magic number and does into indicate the meaning of the value. Correct style declares and initiates a const variable at the top of the function and then later uses it in the code.

const double COST_OF_LARGE_PIZZA = 14.88;
totalCost = numberOfLargePizzas * COST_OF_LARGE_PIZZA;

The end goal is to 1) make the code easier to read, and 2) make the code easier to maintain so if/when the pizza cost is updated, the only change is it at the declaration.

As with anything, there are exceptions for using literals in the body of code. Common mathematical formulas are good examples:

circumference = 2 * PI * radius

In this case there is not good name to replace the 2, and if the literal were replaced with a constant, it would probably make the formula less readable. Also, since it is a mathematical axiom, the value would not be changing in the future, so nothing is gained with a constants. Such situations occur rarely in general. When in doubt though, prefer using a constant.

The literals 0 and 1 are also notable exceptions. Here are some guidelines for when to use such literals

• Initializing variables at declaration including index variable in loops
• Initializing or reinitialization indices or counts
• Incrementing or decrementing variables—though pre/post-increment or pre/post-decrement operators should be preferred
• Return values from methods or functions: return 0 or return 1
• Simple boundary and index adjustments of variables: i < str.size() - 1

Note that just because a value is 0 and 1 does not mean it should never be a constant. In fact, in cases except for the above, a 0 and 1 should be a constant. For example, a specification may state that 1 large pizza feeds 7, a medium 3, and a small 1. 7 and 3 are obvious magic numbers. But so is 1, both because the meaning of 1 in the coding context may not be obvious, and because the number of people a small pizza feeds may change.

It is important to note that constants can be abused. Two common abuses are

1. const int ZERO = 0; This constant accomplishes nothing of use. It does not make the code more readable (0 and ZERO are equivalent) and it does not make things more adaptable–the value of ZERO will never be changed.
2. const int FIVE_YEAR_LOAN = 5; The issues are the same as the previous example. A more appropriate name would be TERM_OF_LOAN_IN_YEARS, which is both descriptive and is obvious to change later if needed.

Here are other example of where using a constant is expected and appropriate:

• A constant to set the random seed for random number generators: rand() % RAND_RANGE + RAND_OFFSET
• Calls to format cout: setprecision, sets, iomanip etc.
• Floats usually are never compared directly for equality, so use a constant is appropriate: (x – y < FLOAT_EPSILON)
• Options for error codes or user input: userOption == QUIT_OPTION

As a final note, string literals are a little different than number literals so magic strings are treated differently than magic numbers. If for example the code is if (userOption = “quit”), “quit” is a magic string. In most of these situations the string is already readable, and just used in one place, so a constant is not required.

• Names should use camelCase (with the first letter lower‐case) or delimiter-separated words that use lower case letters and underscores as delimiters.
• Names should be descriptive, but not burdensome, and strive to avoid needing a comment header for further clarification.
• The body of the function or method should typically less than 20 lines and at most 40 lines.
• Do one task. For example, a function should not 1) return the total number of words in a document and 2) capitalize the first letters of all the words. Each of these should be in a separate function unless there is a compelling reason to do otherwise which should be documented in the code.
• Don't repeat yourself (DRY). There should not be duplicate snippets of code.
• If passing a large data structure, prefer passing by reference, and if that structure is not intended to be updated, then prefer passing by const reference. Using standard variable naming conventions for const parameters (e.g., these are not constants in the code and should not be named in all caps).
• Variables and constants should be declared at the beginning of the scope in which they are used.
• Functions and methods should assert assumption on parameters. For example, if there is an assumption that a pointer is not null, such an assumption should be asserted: assert (boxPointer != NULL);. Or as another example, if an integer parameters is assumed to be positive in the code, such an assumption should be asserted: assert(numCars > 0);. Asserting assumptions is another form of self-documenting code and helps others use the code as it was intended by the original author.

The size limit and one-task requirement affect the complexity of the code. Generally shorter code is simpler to write, easier to understand, and less likely to have defect than longer code. Like any guideline though, it is just a guideline. The ability to read and maintain the code is the high-order bit that overrides these guidelines. If something a bit longer or that does multiple things is easier to understand, maintain, and test, then do it.

• Class naming is CamelCase with uppercase first. Member functions follow the same naming rules as functions.
• Always create a default constructor for each class, and create a parameterized constructor(s) when needed (usually). You may combine these into one constructor function by creating a default constructor with default parameters.
• Any member function that not mutate data members should be declared as const.
• All data members and helper functions should be private or protected.
• Non-primitive parameters should be const-references when appropriate.

• Write self documenting code. Self‐Documenting means that a person reading your code can understand what it is doing without the need of extra comments; therefore, self-documenting code does not have many comments by definition. This mindset does not absolve the need for comments—they are still required—it implies that they only appear in the more esoteric or complex parts of the code.
• There are time when a global variable is the right thing to do, but those times are rare. Be sure that if a global variable is being used, then it is both warranted and justified; warranted and justified means that doing it any other way degrades the readability, maintainability, or testability of the code.
• There are times when a goto-statement is the right thing to do, but such times are near extinct. Be sure that if a goto-statement is employed, then it is more than obvious to why it is necessary.
• break-statements and continue-statements are powerful tools but not used often. Be sure, as with other discouraged statements, uses are merited and justified in terms of readability, maintainability, or testability.
• Use “endl” rather than “\n” — it C++ after all.
• Declare the main function to return an integer, int main(). A 0 return value means everything ran without issue. A non-zero value indicates otherwise. Non-zero values can have meaning that should be documented somewhere.