Executive Summary *

This document covers the coding standards and requirements that will be used by the US Software Capstone design team. It includes file and function headers, symbol naming conventions, commenting standards, whitespace standards, and several miscellaneous rules and suggestions for programmers.

2. File Naming Conventions

 

File naming conventions will follow the form imposed by the Java language. All class files must have the same name as the main class contained therein. File extensions for class files are ".java". User manuals or technical documents will have descriptive names and the file extension ".doc". Output files in the Snoop2 format will have a user defined file name with the required ".snp" extension. Text file output will have a user defined file name with the file extension ".txt". Other types of output files will have a descriptive name and a file extension that suits the format.

 

3. Prologue Standards

 

1. File Prologue Format

1. A backslash followed by thirty asterisks.
2. An empty line.
3. The word "Filename:" followed by the name of the file.
4. The words "Class List:" followed by a list of all classes defined in the file, the main class first (the main class being the class named the same as the file).
5. The word "Description:" followed by a general description of the contents of the file.
6. The word "Author:" followed by the name or names of programmers that contributed to the code.
7. The word "Revisions:" followed by the day, month and year of the each change to the code and a brief description of the change.
8. An empty line.
9. Thirty asterisks followed by a backslash.

1. Class Prologue Format

1. A backslash followed by thirty asterisks.
2. An empty line.
3. The word "Class:" followed by the name of the class.
4. The word "Description:" followed by a brief description of the class.
5. The word "Methods:" followed by a list of methods.
6. The word "Author:" followed by the name of the programmer who wrote the class
7. The word "Revisions:" followed by the day, month and year of each change to the code.
8. An empty line.
9. Thirty asterisks followed by a backslash.

1. Module Prologue Format

1. A backslash followed by ten asterisks.
2. The word "Method:" followed by the name of the method.
3. The word "Description:" followed by a brief description of what the method accomplishes.
4. The word "Input Parameters:" followed by a list of input parameter types and names and an indication if the parameter is changed within the method.
5. The word "Return Value:" followed by the return type. If the method does not return a value, the word "none" will be used.
6. The word "Files Accessed:" followed by a list of files accessed or created by the method. If no files are accessed, the word "none" will be used.
7. The word "Classes Accessed:" followed by a list of other classes and their methods called by this method. If no other classes or methods are accessed, the word "none" will be used.
8. Ten asterisks followed by a backslash.

1. Symbol Naming Standards

 

1. Variable Naming

1. All lower case.
2. Descriptive.
3. Short as possible, keeping legibility and descriptiveness.
4. Will not make use of underscores.

1. Method Naming

1. Start with a capital letter.
2. Will contain a new capitol letter for every new word in the name.
3. Descriptive.
4. Short as possible, keeping legibility and descriptiveness.
5. Will not make use of underscores.

1. Constant Naming

1. Commenting Standards

 

1. Commenting Variables

1. Simple counter variables (e.g. for( int i = 0; i > 10; i++))

1. Commenting Control Structures

 

Every control structure will be commented. The comment will explain the logic performed by the control structure. The comment will precede the control structure and will take the form of double backslashes before each comment line.

 

Example:

//Exit if total nodes are counted, else continue

if ( total = nodenum )

return;

 

2. Commenting Other Code Segments

1. Whitespace Standards

 

1. Indention Rules

 

Nested control structures will be indented three spaces for clarity.

 

2. Usage of Blank Lines

 

Blank lines will be used to separate classes in a file. They can also be used internal to a class to separate code into logical blocks.

 

2. Other Standards

 

The following are guidelines to programmers, and can be broken if circumstances demand. Clear, clean code shall be maintained, and deviation from these guidelines should be well commented as to the reason and effects of the deviation.

 

1. Global Variables

 

Use of global variables is discouraged.

 

2. Function Length

 

Functions of excessive length should be avoided. As a rule of thumb, any function in excess of 200 LOC will be considered long. Long functions should be evaluated to see if it is possible or desirable to break into sub-functions.

 

3. Braces

 

Braces for blocks of code will be placed on their own lines to make tracing nested control structures clearer.

 

4. Clarity vs. Brevity

 

Coding clarity will take precedence over brevity if a conflict arises.

 

5. Operators

 

Spaces will be maintained between operators an their operands.

 

6. Parenthesis