Style Requirements
CS 202: Programming Systems
The following describes the style requirements when
programming in C++ for CS202. The primary requirement is the development of a consistent
style in the use of (a) identifier names, (b) blank spaces, and (c) use of
comments. The following represents a style recommended by your instructor. Make
sure to use only prefix increment/decrement unless the postfix functionality is
required. Make sure to line up curly brackets whenever possible. Always pass
class objects or structs by reference or by pointer
(never by value). Never return class objects or structs.
And, lastly, make sure to indent after each opening curly bracket.
Every project in CS202 will have multiple files (.h and .cpp) – make sure to have clear header comments for each
file describing the purpose of the prototypes, functions, classes that are
specified in that file. In addition, every function you write must have a
header comment describing the purpose of that function.
The
following describes the style requirements when programming in C and
C++:
#1) Comments must use correct spelling and grammar.
#2) Use the
conventions for all variable, constant, and function names:
a)
Use
mnemonic names that have a clear and
understandable meaning.
b)
Always
begin with a letter; an identifier cannot begin with a digit
c)
An
identifier must consist of letters, digits, or underscores only.
d)
Use
all lower case letters (no
capitalized or upper case variables)
e)
Separate
multiple word variables by an underscore
f)
Use
meaningful words that represent the function of the variable
#3) In C Programs: All variable
definitions/declarations must be placed before the executable statements of a
block ({
... }). This means that variable declarations
cannot be scattered throughout your code! C++ allows otherwise.
#4) Only place
one statement per line. C and C++ allows multiple
statements to appear on the same line; however, for style please limit yourself
to only one per line.
#5) For style,
place a blank space between words and operators in a program line. Always leave
a blank space after a comma. Always leave a blank space before and after the
arithmetic and logical operators.
#6) Indent each
line of the program except for the curly braces that mark the beginning and end
of the main program. All lines between the {} are to be
indented two or more spaces consistently.
#7) Use blank lines between sections of
the program. For example, there should always be a blank line between the
compiler directives and the rest of the program. There should also be a blank
line between each block.
#8) Do not
place a blank line between every line of code; this reduces program readability,
instead of enhancing it!
#9) When choosing between an if/else
control statement and using the conditional operator (?:),
always choose the if/else structure. This is required to assist debugging and
readability.
#10) Indentation for if/else control
statements:
if (conditional expression)
{
statement;
statement;
}
else
{
statement;
statement;
}
#11) Indentation for Switch control
statements:
switch (selector expression)
{
case label1 : statement;
statement;
break;
case label2 : statement;
statement;
break;
default : statement;
break;
}
a)
Notice: For style always use the default label.
b)
Place only one case label per line
c)
Always place a break after the last case label -- even though it is
syntactically unnecessary. If you decide to add more labels later on ... you
just might forget to add the break at that time.
#12) The use of
goto's and global variables is not allowed in this class.
#13) Indent loops as follows:
for(i=1; i<=some_max; ++i)
{
statement;
statement;
}
(continued on the next page)
i = 0;
while (i <= some_max)
{
statement;
statement;
}
do
{
statement;
statement;
} while (i <= some_max);
a)
Avoid changing the loop control variable inside of the body of a for loop!
#14) When
writing your own functions, use the following style guidelines:
a) Always use a return at the end of a
function; if the function is not supposed to return a value then end the
function with:
return;
b) Functions that do not have any
parameters must have the term "void" side the parentheses of the
function declaration:
data_type function_name (void);
c) Functions that do not return any
value to the calling routine must be declared with a "void" data_type:
void function_name(parameters);
d) The rule you should live by is: NO
GLOBAL VARIABLES. Instead, use formal parameters to input the data and output
the result. And, use local variables to assist with any intermediate
calculations.
#15) When writing your own .h files,
uses these guidelines:
a)
In .h files, put with each function prototype a clear description of
what it does. In the .c files, put in the header of each function a clear
description of how it does its job.
b) In implementation code for all
functions which are not trivial: break the code into paragraphs. Before each paragraph put white space and a
comment describing what and/or how this paragraph of code does its job.
c) In .h files, place your structure
definitions, class interfaces, and function prototypes. Do not place
function definitions (i.e., the implementation of your functions) in these
files.
d) Never (unless working with templates)
include .c files...only .h files!
#16) When
writing your own classes in C++, use the following style guidelines (these
guidelines do not apply to the C language):
a)
Place the public section first, followed by the private and protected sections.
b) Objects should be named using proper
nouns, such as a_list, my_list,
the_vehicle, a_peach, etc.
c) Classes, on the other hand, should be
named using noun phrases, such as todo_lists,
vehicles, peaches.
d) Operations (member functions) that
can be performed on classes should be named with an active verb, such as
retrieve, create, check, add_an_item, delete_an_item, modify, etc.
e) Always separate the implementation of
a member function from the class header; place the class headers in a ".h" file and the implementation of the member
functions in a corresponding ".c" file (unless you are creating
inline member functions). Never
“include” a .c file...only .h files!
f) The public interface (including its
comments) should be self-contained and meaningful without looking at private
data
g) When using dynamic memory in your
classes, make sure to write a destructor to deallocate
all dynamically allocated memory.
h) When using dynamic memory in your
classes, make sure to write a copy constructor and overload the assignment
operator to perform a deep copy operation. Never pass an object to a
function by value unless a copy constructor has been implemented.
i) Whenever possible, pass objects to
functions as constant references. Minimize the need to create local copies.
j) Whenever overloading the arithmetic
operators (e.g., +), also overload the compound assignment operators (e.g., +=).
k) Use the following indentation:
class todo_lists
{
public:
//constructor(s)
//copy
constructor
//destructor
//data
members
//member
function prototypes
private:
//data
members
//member
function prototypes
protected:
//data
members
//member
function prototypes
};