Code Formatting Standards and Guidelines
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.,
public double 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;"
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 4
* Name: Barbara Smith
* E-mail:
bsmith22@brynmawr.edu
* Course:
CS 110 - Section 01
* Submitted: 1/10/2011
*
* The main driver program
for project 4.
* 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)
*
***********************************************/
public 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 (format: "@param
variableName the description of the variable")
- a description of the function's outputs (format: "@return the description
of the returned value")
- side effect of the function (if any -- this should be rare)
For example:
/** Calculates the area of
a circle with the specified radius
*
* @param radius the
radius of a circle
* @return 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
int arrayLength = array.length;
for (i = 0; i < arrayLength;
i++) {
// add
1 only to the odd values
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[<br>
]]>