The Following Presents the Style Conventions You Are Expected to Follow When Writing Programs

11/20/181

C++ Style Guide

The following presents the style conventions you are expected to follow when writing programs in this class. In many ways, style is as important to understanding how a program works as is the logic and implementation itself.

1. Comments

Comments should describe what things are happening and how they are being done when it is not obvious from the code itself. Comments that simply parrot the code are of little value.

a. Single-line comments

// This is a single line comment

b. End-of-line comments

Short comments can be placed on a line with code, but make sure all such comments start and end in the same column. This style is good for named constants and initialization.

x = 10; // set initial x coordinate

y = 20; // set initial y coordinate

c. Multi-line comments

// This is a comment, which if it said anything meaningful

// would take more than one line.

d. Comments and Indentation

Always indent comments to the same level as the code that they describe.

// Read data from file until EOF

while (inFile)

{ // Get a character from the input file and print it.

inFile.get(currChar);

cout < "The current character is " < currChar;

}

e. Program prologue comments

Every program should begin with a series of comments that contain information related to the program as a whole. There are three sections that need to be included: one that tells who wrote the program, when, etc., a second that describes the purpose of the program, and a final section that describes the input and output associated with the program. Your programs should always contain this information. There may be additional things you would like to mention (e.g., how to compile your program, system dependencies) that can also be included.

//**********************************************************************************

// Your Name:

// Course Number:

// Lab Number:

// Date due:

// Purpose: Describe what the program as a whole does (e.g., calculates a payroll). // This need not be long, just a couple of sentences will do. Many students // mistakenly describe the purpose of the assignment here (e.g., to learn // how to use functions), rather than the purpose of the program.

// Input: This section is very important for anyone (including yourself) who may // want to use this program. There are usually four things that are useful to // know about a program's input:

// 1. What is the input? What information does the program expect to receive // in order to run correctly?

// 2. What is the format of the input? If the input is coming from a file, // the data is probably laid out in specific columns.

// 3. From where does the program expect to receive the input? Does the // program read from the keyboard (cin) or a file? If it reads from a // file, where and what is the filename?

// 4. Sometimes there are program restrictions in terms of the input that you // may want to mention. For example, "the maximum number of students that // can be read is 50" or "definitions can be no longer than 250 // characters".

// Output: This section is similar to the input section, but of course, describes // what is output instead. It should include information about the contents // of the output, general format (e.g., a table), where the output is sent // (cout or a file), the names of any files created, and any other relevant // information.

//**********************************************************************************

f. Embedded comments

An alternative form of comments that are embedded in a line of code uses the /* */ convention from C. The comment must include the ending marker */ This form of comment is generally used in the formal parameter list of a function to explain how each parameter is used. Also, embedded comments indicate which of the data flow categories each parameter belongs to.

void FindMaximum (float /* in */ first,

float /* in */ second,

float /* inout */ largerValue);

g. Function prologue comments

After the function heading, you must describe the purpose of the function. You should also describe the pre- and port-conditions.

// Purpose: Find the larger of two input parameters

// Precondition: first and second have been initialized or set

// and have been tested for valid data.

// Postcondition: largerValue will contain the larger of the two

// values.

2. Naming Conventions

a. Named constants

All named constants should use uppercase letters.

const float PI = 3.14159;

const int MAXROWS = 15;

b. Variables

All variables should be meaningful nouns that begin with a lowercase letter. If you use compound words, use an underscore to separate each word or capitalize the beginning of each successive word.

float price, accountBalance, milesPerGallon;

char code_letter, middle_initial;

c. Functions

Function names should begin with a capital letter. Void function names should be imperative verbs or phrases containing imperative verbs whereas value-returning function names should be nouns or adjectives.

void GetData (/* parameter list */);

void PrintTable (/* parameter list */);

float CubeRoot (/* parameter list */);

int Color (/* parameter list */);

float AreaOf (/* parameter list */);

bool IsInRange (/* parameter list */);

d. Typedefs

Each word in a typedef name should begin with an uppercase letter.

typedef double Vector[SIZE];

typedef char LastName[NAMELENGTH];

typedef int Time;

e. Enumeration Types

The name of the enumeration type should begin with an uppercase letter. The enumeration values should be all uppercase.

enum Days {SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY};

enum StopLight{RED, YELLOW, GREEN};

3. Whitespace (spaces and blank lines)

Whitespaces should be used to clearly separate program elements.

a. Spaces

Use spaces between all binary operators, following punctuators, and to align code.

int i;

float x;

a = (2 * b) - c / d;

if (x < 1)

b. Blank Lines

Use a blank line to separate sections of code that are unrelated. For example, use a blank line after the #include directives.

#include <iostream.h>

#include <math.h>

const float PI = 3.14159;

int main ()

{

int i, j;

cout < "dumb example" < endl;

return 0;

}

4. Indentation and Style

Use the same number of spaces each time you indent, preferably 2 or 3 spaces.

a. Variables

Group related variables on the same line. Unrelated variables should be declared on separate lines even if they are of the same type. Align variables after the type.

double rateOfPay, netPay, grossPay;

double monthlySales;

int i, j, k;

b. if statements

While C permits an if statement to be completely written on a single line, you should always write the condition on one line and the "action" on a separate line.

if (expression)

statement;

if (expression) if (expression)

{ { statement_1;

statement_1; statement_2;

statement_2; }

}

if (expression)

statement-1;

else

statement_2;

if (expression) if (expression)

{ { statement_1;

statement_1; statement_2;

statement_2; }

} else

else { statement_3;

{ statement_4;

statement_3; }

statement_4;

}

c. while statements

while (expression) while (expression)

{ { statement_1;

statement_1; statement_2;

statement_2; }

}

d. for statements

for (stmnt_1; expr; stmnt_2) for (stmnt_1; expr; stmnt_2)

{ { stmnt_3;

stmnt_3; stmnt_4;

stmnt_4; }

}

e. switch statements

switch (expr)

{ case exp: stmnt_1;

stmnt_2;

break;

case exp: stmnt_3;

stmnt_4;

break;

default: stmnt_5;

stmnt_6;

}

f. functions

The function return type, function name, and first parameter should appear on the first line of the function beginning in column 1. The remaining parameters should each be on a separate line with their associated comments aligned with the data type of the first parameter.

float AcctBalance (float /* in */ PreviousBalance,

int /* in */ DaysInMonth,

float /* in */ InterestRate); /* update account balance */

5. File Organization

The order of things within a file is:

1. program prologue comments

2. #include header files

3. named constants

4. function prototypes

5. main function

6. remaining functions, each with its function prologue comments

PROGRAM PROLOGUE COMMENTS

//**********************************************************************************

// Your Name:

// Course Number:

// Lab Number:

// Date due:

// Input: This section is very important for anyone (including yourself) who may // want to use this program. There are usually four things that are useful to // know about a program's input:

// 1. What is the input? What information does the program expect to receive // in order to run correctly?

// 2. What is the format of the input? If the input is coming from a file, // the data is probably laid out in specific columns.

// 3. From where does the program expect to receive the input? Does the // program read from the keyboard (cin) or a file? If it reads from a // file, where and what is the filename?

//**********************************************************************************