1.0 SCOPE

1.1 Purpose -Insure the maintainability of software products. Provide for an efficient software development process by improving the readability of documents and for the automation of common tasks.

1.2 Applicability - This standard applies to all product documents

1.3 Authority - The interpreting authority for this standard is the Manager of Engineering

2.0 APPLICABLE DOCUMENTS

Latest revision of all documents listed in this Section shall apply.

2.1 Referenced Documents

STD ES - Engineering Standards
STD ES - Engineering Documentation
STD ES - Control of Product Design Documentation
Drafting Manual

2.2 Related Documents

``The Practice of Programming'', Kernighan, Brian W., and Rob Pike, Addison Wesley,
Reading, MA, 1999

3.0 GLOSSARY

Product Document: Derived requirement documents, design documents, test documents, rule sets, computer source code and scripts. Any document or file required to be maintained in the course of developing the final product.

Source Document: Any document from which a Product Document or part of a Product Document should have been derived. Source documents are not generally under the control of project teams.

4.0 REQUIREMENTS

4.1 GENERAL

4.1.1 This standard adopts and extends the requirements of STD Engineering Documentation.

4.1.2 Each document shall have front matter or a header that contains at least the following :

a) project identification
b) repository (file) name and location
c) author name(s)
d) date of initial release
e) short description
f) revision history

4.2 PRODUCT DOCUMENTS

4.2.1 For tracability each requirements document shall be written such that each requirement is uniquely identified. The identification scheme shall be such that it is easily search-able using automated tools.

4.2.2 Product documents shall contain information that assists tracability to higher level Source Document requirements.

4.3 COMPUTER SOURCE CODE

4.3.1 NAMES

Use long descriptive names for globals, short names for local items. Very short names (one or two letters) may be used where language idiom makes the meaning apparent.

Apply a consistent naming convention.

Do not use misleading, unpronounceable, or redundant names

Give constants, array sizes, conversion factors, and other literal numeric values names descriptive of use.

4.3.2 EXPRESSIONS and STATEMENTS

Indent to show structure. Parenthesize to resolve ambiguity and to make intent clear.

Use the natural form for expressions, as you would in speech. Avoid logical negation as much as possible.

Break up long complex expressions for clarity. Expressions should not contain more than five operators or modifiers.

Be careful of side effects. Do not rely on side effects.

Do not apply autoincrement or autodecrement operators to a variable more than once in any expression.

For long or complex logical expressions, break the expression after a logical operator.

Use else-if for multi-way decisions. Avoid nested if statements.

Use the language to calculate the size of an object.

4.3.3 CONSISTENCY

Use idioms for consistency.
Apply a consistent indentation and brace style throughout.
Apply consistent rules of capitalization and punctuation.

4.3.4 MACROS

Do not use function macros

Define numbers as constants not macros.

4.3.5 COMMENTS

Commented out code not permitted in released code.

Use comments to clarify the code, not repeat the code. There is no advantage and many disadvantages to excessive use of comments

Comment functions to clarify and explain the algorithm, parameters passed in and out, and intended usage.

Each function definition shall have a heading comment that :

a) Explains the purpose and use of the function,
b) Lists all variables use and any global variables modified.

Comment global data to show its intent and usage

Insure that comments reflect the code. Update the comments each time the code is revised.