Code Formatting Standards
All organizations and companies have specific conventions for
formatting code. While these formatting rules may vary from
place
to place, they are essential for making your code readable and for
enabling others to understand, use, and modify your code in the
future.
For these reasons, we will be using the following coding standards
in
this class. Adherence to these standards will be a portion of
your grade on each assignment.
Naming Conventions
- Use meaningful names!! For example, if your program
needs a
variable to represent the radius of a circle, call it radius,
NOT r
and NOT rad.
- Use single letter variables ONLY for simple for
loop
indices.
- The use of very obvious, common, meaningful abbreviations is
permitted. For example, "number" can be abbreviated as "num" as
in numStudents.
- Begin variable and function names with lowercase letters
- Begin class names with uppercase letters
- Use all uppercase for symbolic constants (e.g., const
float PI =
3.14;)
- Be consistent!
- Separate words within identifiers with mixed upper and
lowercase.
For example,
- Variables: grandTotal, circleRadius
- Functions: computeArea, saveFile
- Classes: CircleTable, PieChart
Whitespace
The most-readable programs are written with prudent use of
whitespace
(including both blank lines and spaces).
- Use blank lines to separate major parts of a source file or
function.
- Separate declarations from executable statements with a blank
line.
- File and class header comments begin in the first column, all
function definitions are indented one column to the right.
- All statements in the body of a function are indented beyond
the
function definition. Statements inside of a loop or part
of an if
structure are indented further.
- Use spaces around all operators. For example, write "x = y + 5;"
instead of "x=y+5;"
Comments
File Header Comments
Every source code file
should
contain a header comment that describes the contents of the file and
other pertinent information. It must include the following
information:
- The assignment number
- Your name
- Your school e-mail address
- The class and section number
- The date the assignment was submitted
- A description of the contents of the file
For example:
/*****************************************
*
Assignment 1
* Name: Barbara Smith
* E-mail: bsmith22@brynmawr.edu
*
Course: CS XXX - Section 01
* Submitted: 1/10/2013
*
*
The
main driver program for project 1.
*
This
program reads the file specified as the first command line
*
argument, counts the number of words, spaces, and characters and
*
displays the results in the format specified in the project
description.
*
***********************************************/
Class Header Comments
Every class should
contain a header comment that includes the following information:
- A description of the class and its purpose
- Your name and e-mail address
For example:
/*****************************************
*
Represents a single-family residential home, including
*
all
exterior features of the house, and its location.
*
*
Author: Barbara Smith (bsmith22@brynmawr.edu)
*
***********************************************/
class
House {
...
}
Function Header Comments
Every function must have a
header comment that includes the following:
- a description of what the function does
- a description of the function's inputs
- a description of the function's outputs
- side effect of the function (if any -- this should be rare)
For example:
/** Calculates the
area of a circle with the specified radius
*
Parameters:
*
radius : the radius of a circle
*
Returns the circle's area
*/
double
circleArea (double radius) {
...
}
In-Line Comments
The basic rule of thumb is that you should be able to delete all of
your code and then regenerate a working program from only the
comments.
- Comments explain
what
your code does; they do not
describe how it does
it.
- Well-structured code will be broken into logical sections that
perform
a simple task. Each of these sections of code (typically
starting with
an 'if' statement, or a loop or a 'switch') should be
documented.
- A particularly important line of code should also be
commented.
- Do not comment every line of code. Trivial comments
(e.g.,
//increment x)
are
worse
than no comments at all.
An in-line comment appears above the code to which it applies and is
indented to the same level as the code. For example:
// increment all
the odd values in the array
for (i =
0; i
< arrayLength; i++) {
if
(array[i]
%
2 == 1) {
array[i]
=
array[i]
+ 1;
}
}
Endline comments should very
rarely
be used, and then only to explain particular aspects of a line, such
as
what a variable means or some pecularity:
int width =
widestXCoord/2 % 11; // divisor must always be a prime
number
Indentation Styles
Choose one of the two styles and use it consistently
if
(condition)
{
if
(condition)
...
{
} else if
(condition)
{
...
...
}
} else
{
else
if
(condition)
...
{
}
...
}
else
{
...
}
for (loop
control expressions)
{
for
(loop
control expressions)
...
{
}
...
}
while
(condition)
{
while
(condition)
...
{
}
...
}
do
{
do
...
{
} while
(condition);
...
}
while
(condition);
switch
(variable)
{
switch
(variable)
{
case
constant1:
...
{
break;
case
constant1:
...
case
constant2:
...
break;
break;
case
constant2:
...
case
default:
...
break;
}
case
default:
...
}
<![CDATA[&lt;br&gt;<br>
]]>