Table of Contents

Forecast Systems Laboratory

Changes to this Version
General Changes
Convention Wording Changes

Table of Contents

Introduction
Convention Goals

1. Use of Standards
Conventions
1.1 Language Standards
1.2 Use of Standard Libraries
1.3 Use of Vendor-Specific Extensions
1.4 Use of Standard Header Files
Rationale

2. Statement Formatting
Conventions
2.1 Use of Printable Characters & Line Length Limitations
2.2 Placement of Simple Statements
COMPLIANT EXAMPLESNONCOMPLIANT EXAMPLE
A UNIQUE EXCEPTION - widely used with the X11 Toolkit to clarify bookkeepping while avoiding macro side-effects
2.3 Standard Indentation
2.4 Compound Statement Format
COMPLIANT EXAMPLES
2.5 Control Statement Format
COMPLIANT EXAMPLE NONCOMPLIANT EXAMPLES
2.6 Function Definition Format
EXAMPLE OF A COMPLIANT FUNCTION
COMPLIANT EXAMPLE NONCOMPLIANT EXAMPLES
2.7 Do-While & Typedef Statement Formats
COMPLIANT EXAMPLES
2.8 Nested If Statement Format
COMPLIANT EXAMPLE
2.9 Chained Else If Clause Format
COMPLIANT EXAMPLE
2.10 Use of Comma Operators & Delimiters
COMPLIANT EXAMPLES
NONCOMPLIANT EXAMPLES
Rationale
NONCOMPLIANT STYLES OF BRACE PLACEMENT
COMPLIANT STYLE OF BRACE PLACEMENT
NONCOMPLIANT EXAMPLE
NONCOMPLIANT EXAMPLE
NONCOMPLIANT EXAMPLE
SAME NONCOMPLIANT EXAMPLE (as interpreted by the compiler)
COMPLIANT EXAMPLE
COMPLIANT EXAMPLE
NONCOMPLIANT EXAMPLE

3. Spacing & Delimiters
Conventions
3.1 Use of Parentheses
COMPLIANT EXAMPLESNONCOMPLIANT EXAMPLES
3.2 Use of Spacing
3.3 Spacing Around Control Keywords
COMPLIANT EXAMPLESNONCOMPLIANT EXAMPLES
3.4 Continuation of Long Statements
COMPLIANT EXAMPLE (function definition)
COMPLIANT EXAMPLE (function reference)
COMPLIANT EXAMPLES (correct selection of breaking points)
NONCOMPLIANT EXAMPLE (excessive indentation to accomodate vertical alignment)
NONCOMPLIANT EXAMPLE (excessive indentation and continuation)
NONCOMPLIANT EXAMPLES (noncompliant indentation and/or breaking points)
3.5 Spacing Within Expressions
COMPLIANT EXAMPLES NONCOMPLIANT EXAMPLES
COMPLIANT EXAMPLES NONCOMPLIANT EXAMPLES
COMPLIANT EXAMPLES
Rationale

4. Identifiers
Conventions
4.1 Identifier Convention Applicability
4.2 Composition of Identifiers
4.3 Selection of Identifiers
COMPLIANT EXAMPLESNONCOMPLIANT EXAMPLES
4.4 Identifier Lengths
COMPLIANT EXAMPLESsingle identifier within context multiple identifiers within context
Note how context is modified below through the use of structures. Structure members need only be differentiated from other members within their structure.
4.5 Prefix for Public Identifiers
4.6 Identifier Formats
4.7 Reserved Keywords
RESERVED KEYWORDS & ENTRY POINTS
Rationale

5. Data Types & Declarations
Conventions
5.1 Declaration Placement
5.2 Declaration Format
COMPLIANT EXAMPLE
NONCOMPLIANT EXAMPLE - Alignment of identifiers is generally not feasible without sorting by type. Adding a register qualifier to the example below defeats any intentioned alignment.BEFORE:
AFTER:
NONCOMPLIANT EXAMPLE (continuation of declarations)
5.3 Use of Descriptive Types
COMPLIANT EXAMPLES
5.4 Variable Initialization
5.5 Distinction Between Structures and Classes
5.6 Class Declarations
COMPLIANT EXAMPLE (contents of C++ class header file)
5.7 Aggregate Type Declarations
COMPLIANT EXAMPLE (C or C++) COMPLIANT EXAMPLE (C++ only)
5.8 Use of Aggregate Tags
COMPLIANT EXAMPLE (C or C++)
5.9 Bit Fields and Flagwords
COMPLIANT EXAMPLE NONCOMPLIANT EXAMPLE
5.10 Flagword Declarations
COMPLIANT EXAMPLE
5.11 Integer Portability
5.12 Use of the Void Pointer Type
COMPLIANT EXAMPLE
NONCOMPLIANT EXAMPLE
Rationale
UNNAMED - Non-compliant; requires duplication of type declarations within each variable declaration.
TAGGED - Non-compliant in C, but compliant in C++; tags reside in separate name spaces, allowing duplicate use of identifiers. Requires use of struct, union, or enum keywords within variable declarations.
NAMED+TAGGED TYPES - Compliant for self-referencing or mutually referencing types in C. Tag and type names are intentionally made identical, so that variables may be declared using type names without confusion. (also compliant in C++ for files common to C and C++).
NAMED TYPES - Compliant for all but self-referencing or mutually referencing types in C. Defines a type name only (no tag). (Compliant in C++ for files common to C and C++).
C++ NAMED TYPES -Compliant in C++, unless compatibility with C is a concern.

6. Comments
Conventions
6.1 The Purpose of Comments
6.2 Comment Format
COMPLIANT EXAMPLES
6.3 Comment Placement
6.4 Excessive Commenting
6.5 Comments and Braces
COMPLIANT EXAMPLENONCOMPLIANT EXAMPLE
6.6 Wording Within Comments
COMPLIANT EXAMPLES
NONCOMPLIANT EXAMPLES
Rationale

7. Source File Organization
Conventions
7.1 File and Function Headings
FILE HEADING TEMPLATE (Bracketed items are replaced with actual information)
FUNCTION HEADING TEMPLATE (Bracketed items are replaced with actual information)
EXAMPLE OF A COMPLIANT FILE HEADING
EXAMPLE OF A COMPLIANT FUNCTION HEADING
7.2 Source Module Organization
SOURCE MODULE TEMPLATE (Bracketed items are replaced with actual information)
7.3 Contents of Header Files
7.4 Header File Organization
HEADER FILE TEMPLATE (Bracketed items are replaced with actual information)
7.5 Use of Disclaimers
7.6 Hooks for Heading Extraction
Rationale

8. Functions and Prototypes
Conventions
8.1 Explicit Function Types
8.2 Function Prototypes
COMPLIANT EXAMPLE
8.3 Function and File Size
8.4 Explicit Function Return
8.5 Structure Parameters
COMPLIANT EXAMPLE (C or C++)COMPLIANT EXAMPLE (C++ only)
Rationale
COMPLIANT EXAMPLENONCOMPLIANT EXAMPLE (Returns No Value) (Return Not Specified)
If modified as shown below (modifying function type without modifying return),then the following will result: (will not compile)(returns an UNDEFINED value)
COMPLIANT EXAMPLES
This routine performs a special type of computation.
This routine looks up a command ID associated with a keyword.
This routine processes a graphics command.

9. Semantics
Conventions
9.1 Use of Complex Techniques
9.2 Use of Advanced C++ Features
9.3 Linking C++ Code to C Code
9.4 Protecting Private Variables and Members
9.5 Switch Statement Semantics
COMPLIANT EXAMPLENONCOMPLIANT EXAMPLE
9.6 Use of the Goto Statement
9.7 Use of the Conditional Operator
9.8 Expression Side-Effects
NONCOMPLIANT EXAMPLES
9.9 Use of Null Constants
9.10 Use of Environment Variables
9.11 Overloading of Variable Names in C++
9.12 Function Overloading in C++
9.13 Base Class Destructors in C++
Rationale
COMPLIANT EXAMPLES (equivalent conditional operator and if-else expressions)This example shows the maximum recommended complexity within conditional operator expressions.
COMPLIANT EXAMPLES (equivalent conditional operator and if-else expressions)This use of the conditional operator is appropriate when surrounding control logic is unrelated to s.
COMPLIANT EXAMPLES

10. Constants & Directives
Conventions
10.1 Use of Defined Constants
COMPLIANT EXAMPLE
NONCOMPLIANT EXAMPLE
10.2 Use of Declared Constants
10.3 Use of Macros
COMPLIANT EXAMPLES
NONCOMPLIANT EXAMPLES
10.4 Use of In-line Functions
10.5 Include Directives
COMPLIANT EXAMPLESNONCOMPLIANT EXAMPLES
10.6 Conditional Compilation
COMPLIANT EXAMPLES
Rationale
COMPLIANT EXAMPLES
Version 1: Conditional Directives Intermixed with control phrases.This version eliminates duplication at the expense of readability.It may be difficult to modify, because conditional logic is interwoven with control logic.
Version 2: Conditional Directives brought outside of control statements.This version promotes readability at the expense of duplication.It is much more readily modified, because conditional logic is kept distinct from control logic.

11. Error Handling
Conventions
11.1 Distinguishing Diagnostics From Error Handling
11.2 Error Message Guidelines
11.3 Error Return Codes
11.4 Elaborate Error Handling
11.5 Generation of Diagnostics
Rationale

Appendix A. Terminology
Appendix B. References for Further Reading
Appendix C. Compliance with these Conventions
Expectations Regarding Compliance
Convention Modification
Appendix D. Compliance within a VMS Environment
Appendix E. System-Dependent Development Conventions
File Naming Conventions
Automated Builds and Source Code Control
Appendix F. Building and Controlling Source Code