This document provides a minimal set of style requirements for small to medium size projects. Beyond what's stated here, it's important to create code that promotes readability, re-usability and consistency.
Products are delivered in one of the following formats, as negotiated at project start:
zip
file of all components: source code, stored procedures, etc.
The code provided should be a complete package with all components needed for a 3rd party to install, build and run the product:
COPYRIGHT.txt
(copyright statement, provided)
The recommended directory structure is:
doc
for supplementary documentation
scripts
for ancillary scripts, if any.
src
for source code. Create sub-directories based on language.
test
for test code and sample data
doc/README.txt
as described below
COPYRIGHT.txt
as provided
The following are required supplemental documents.
This data dictionary should include:
A
doc/README
file contains the following:
File names should be understandable to a new programmer reading the code. File extensions should be self-consistent and follow the prevailing industry standard. In object-oriented languages, files should match the class name.
In all cases:
Each file should contain a block level comment indicating the purpose, author and related files. This should include a copyright header (provided).
The following guidelines apply to all functions.
Each public function should contain a block level comment indicating its purpose. (For languages without public/private constraints, all functions are considered public.)
A maximum of five (5) parameters are allowed in strongly typed languages, and three (3) in dynamically typed languages.
Functions should be 50 lines or fewer.
Arithmetic and boolean expressions should have 6 or fewer terms.
Functions should aim for a cyclomatic complexity <= 10. See MCCABE
Parameter, constant and variable names should be understandable to a new programmer reading the code.
In all cases:
Code that is no longer needed should be removed from the project (not commented out). Files not required by the project should not be delivered in the package.
Code that needs further work should be tagged with the comment keyword "TODO" for easy identification.
See these references for more information: