Why Coding Standards?

The code you contribute to PBS will be read by many different people, and will stick around for a long time.  Make it easy to read, learn, and review your code by following the coding standards, and by using standardized interfaces instead of nonstandard.

Contents

C Coding Style

• Use ANSI C style; not K&R

• Do not decorate types (i.e. use char ∗s, not char∗ s).

• put else if on a single line

• use sizeof(variable) instead of sizeof(typeofvariable) so that a change in the type of variable doesn't require a change in the use of sizeof

• when allocating space for an object, use sizeof(*pointer_to_object) rather than sizeof(object_type) to allow type change flexibility

• match a program's usage statement to its man page's SYNOPSIS

• if a variable can take on a limited number of values, or a function can return a limited number of values, choose enum rather than #define for that limited set

• use strtok_r() rather than strtok() (even on Windows -- PBS's win.h header file redefines strtok_r to use strtok_s on Windows platforms)

• when you discover non-ANSI-compliant code, fix it

• use const whenever appropriate

• You don't need braces for single statements

Macros

• Make macro names all upper-case

• Always parenthesize macro arguments in definitions

• If a macro's definition could affect code flow (for example, it expands to either multiple statements or none), surround its use with braces

• Use #define and macros constructively

• Some naming guidelines may lead to long names, and crazily long lines of code. You can shorten unions within structures via #define constructs.

• You can improve code readability with macros.  Compare these

Functions

• Put private function declarations at the top of a source file

• use void and void * where appropriate (e.g. when a function returns no value or with pointers suitable for coercion to any type of object)

• Indent local variable definitions one level. You can put multiple definitions in a single statement

• You don't need to align variable names and trailing same-line comments

• Indent continuation lines of a function's signature in the function's definition or declaration consistently, so that they are easy to read

• use static for scoping as appropriate

• Put a function's opening brace in column one

• Right:

  Wrong:

• Separate a function's type and name by a newline (that is, both the type and name must start in column one). 

• Right:

  Wrong:

• Right:

  If a function does not return a value, don't add a return line at the end

  Right:

  Wrong:

• Right:

  You don't need to cast return values of functions that return void *

• Right:

  Wrong:

• If there are no arguments, use (void) rather than () in the signature

• Right:

  Wrong:

Header Files

• Begin with a licensing notice

• use extern when declaring a function or variable in a header file