2. C Coding Standards

2.1 Introduction to C Programming Standards

This document presents standards and guidelines for programs and library routines written in the C language. The purpose of these standards is to increase portability, maintainability, and readability of procedures developed in ANSI-C.

2.2 Compilers

All C code should be written to the ANSI-C standard. Whenever possible, use standard C library routines.

The strictest compiler warning should be enabled. This is done by using the -fullwarn flag for the SGI compiler or the -Wall flag for the gcc compiler.

Note: Much of the legacy LAS C code has been written utilizing the K&R style. Whenever significant changes are made to the code, the K&R style should be converted to ANSI-C.

2.3 Functions

All functions should explicitly declare their return data type. Function names should be descriptive and fully spelled out.

Legacy LAS code often limits the size of function names by dropping characters. This practice should no longer be followed since modern compilers do not have problems with the number of characters in function names. This practice really makes code difficult to read and maintain.

Legacy LAS code also precedes function declarations with the word FUNCTION. Whenever code following this practice is modified, the word FUNCTION should be removed.

2.4 Global Data Structures

Global data structures should only be used when absolutely necessary (which is almost never).

2.5 Goto

Gotos and labels should be rarely used. This usage should seldom be necessary if proper control structures are used.

2.6 Lexical Rules

Each line that is part of the body of a control structure (if, while, for, functions, etc.) is indented at least 3 characters with 4 being preferred.
Each opening brace "{" or closing brace "}" appears on a separate line aligned with its corresponding mate and aligned with the start of the line preceding it.
Example:
```
     
    while (i < j)
    {
        printf("hello world\n");
        i++;
    }
```
Null statements should be placed on their own line and explicitly commented.
Example:
```
    while (*STT)
        /* Null statement */;
```
To enhance readability, spaces should be placed around all assignment and binary operators, and no spaces should follow unary operators. Only one statement should appear on each line.
Line length should be limited to 80 characters to allow printed output to appear correctly.
Tab characters should not be used in the source code. Using Tab characters complicates maintenance since it makes correct indenting depend on a user's setting for tabstops. (Vi/Vim users can turn off Tab characters with the ":set expandtab" command).

The preferred comment formatting is shown below:

{ /* Comments should be indented the same amount as the line of code they are associated with. Multi-line comments should be aligned as shown here. */ line of code... }

2.7 Optimization

The register specifier should not be used. Modern optimizing compilers ignore it. Remove the register specifier from legacy code during maintenance.

2.8 Macros

Macros should be written in UPPER CASE. Use parentheses around parameters in the replacement text to ensure proper order of evaluation.

Example:

     #define SQUARE(X) ( (X) * (X) )

2.9 Pointers

This is general guidance on the use of pointers.

When declaring pointers without immediately allocating space to it, set the pointer to NULL or zero. This helps reveal access to uninitialized pointers.
When memory is freed, immediately set the pointer to NULL or zero to help catch accesses to freed memory.
Avoid the use of pointer math since it is hard to understand and is not always portable.

2.10 Portability

2.10.1 Operating Systems

When operating system library functions must be used, use routines that are defined in the POSIX standard or Single Unix Specification. Refer to the Single Unix Standard. As a last resort, use system dependent routines with conditionally compiled code for all supported systems.

Note: Much of LAS was developed before the POSIX standard and Single Unix Specification were defined. Developers should convert code to follow these standards as updates are made.

2.10.2 Machine Architecture

Do no assume the following:

Order of bytes in memory (Little Edian vs. Big Edian)
Availability of system commands

Note: LAS has been developed exclusively on Little Edian machines for the past several years. It should work on Big Edian machines, but there may be problems sharing files between the architectures.

2.11 Variable Naming Conventions

All lower-case should be used for variables local to a routine or module.
The first character of a global variable should be upper-case.
Names should be meaningful. For example, use lines instead of i.
Bit fields should be used sparingly since they are not guaranteed to be portable.

2.12 Variable Declarations

short should be used for 16-bit integers.
int should be used for 32-bit integers.
long long should be used for 64-bit integers.

Note: The LAS standard was to use long or short instead of int. For old architectures, long used to always be 32-bit and short used to be 16-bit. This has not been true for many years. Using long is actually not portable since some architectures consider it to be 64-bit. All long declarations should be converted into int during maintenance.

2.13 Parameter Passing

All parameters should be passed by value except for large structures or when values need to be returned.
Parameters that are passed by references(pointers) for input purposes only should be declared as const.
All parameters should be well commented. Include I: for input parameters, O: for output parameters, and I/O: for parameters which are both input and output. When applicable, the comment should define the units of the parameters.

Note: Legacy LAS code passes many variables by reference when it is not necessary.

2.14 Evaluation Order

Do not rely on the order of execution except where guaranteed by C. Explicit parentheses should be used at all times.

2.15 Library Routines

Library routines should be placed in a separate source file (.c) and should also be placed in an appropriate object library. The use of a library ensures that only the modules needed in an application will be linked.

2.16 Conventions

Legacy LAS code often has the "noise word" FUNCTION before function declarations. These should be eliminated during maintenance.

Support library files should only contain a single support library function and any private functions it uses. Applications may be organized with multiple functions in a single file, but they should be closely related functions.

2.17 Programming Notes

Use of "setjump routine" makes debugging a problem. Avoid calling this routine.
Avoid trying to do too many operations in a single statement, for example, misuse of a "for" statement to initialize non-looping variables.