C programming standards (old)

Overview
Introduction
General Recommendations
Source Code in Files
Assigning Names
Style
Classes
Class Templates
Functions
Constants
Variables
Pointers
Type Conversions
Expressions
Memory Allocation
Fault Handling
Portable Code
Terminology

This document is pending revision.

A few rules and recommendations remain to be added. Examples are occasionally missing. Some rules and recommendations need (further) modification for EMBOSS.

Technical terms are highlighted in green and described in the "Terminology" section at the end.

1. Overview

EMBOSS and AJAX will be written entirely in ANSI C. Coding standards are based on the Ellemtel 1992 standards for C++, adapted for C.

2. Introduction

Rule 0 : Every time a rule is broken, this must be clearly documented

3. General Recommendations

Rec. 1 : Optimize code only if you know that you have a performance problem. Think twice before you begin.

4. Source Code in Files

4.1 Structure of Code

Rule 1 : Include header files always have the file name extension ".h"
Rule 2 : Implementation files in ANSI C always have the file name extension ".c"
Rule 3 : Include files containing function source code always have the file name extension ".i"
Rec. 2 : An include file should not contain more than one 'class' definition.
Rec. 3 : Divide up the definitions of member functions or functions more than one file where possible
The standard UNIX linker <ld> links all functions in an object file even if only one of them is actually used. On the other hand, there are problems in managing a large number of files especially when using static data or functions.
Rec. 4 : Place machine-dependent code in a special file so that it may be easily located when porting code from one machine to another

4.2 Naming Files

Rec. 5 : Always give a file a name that is unique in as large a context as possible.
Rec. 6 : An include file for a class should have a file name of the form <class name> + extension. Include file names should always be in lowercase.

4.3 Comments

Rule 4 : Every file that contains source code must be documented with an introductory comment that provides information on the file name and its contents
Rule 5 : All files must include copyright information
This includes reference to the GNU (Library) General Public License if appropriate.
Rule 6 : All comments are to be written in English
Rec. 7 : Write some descriptive comments before every function
Single lines of code may be documented by inline comments where useful. In general, code should be described by the comments which precede the function in preference to excessive comments within the code.
Rec. 8 : Use comment blocks with "/*" on the first line, "*/" on the last line, and "**" for lines in between.

4.4 Include Files

Rule 7 : Every include file must contain a mechanism that prevents multiple inclusions of the file.
The easiest way to avoid multiple includes is by using an #ifndef/#define block using the variable FILENAME_H in uppercase in the beginning of the file, and an #endif at the end of the file
#ifndef FILENAME_H #define FILENAME_H ........ #endif /* FILENAME_H */
Rule 8 : Never specify relative UNIX names in #include directives.
Rule 9 : Every implementation file is to include the relevant files that contain:
- declarations of types and functions used in the functions that are implemented in the file.
- declarations of variables and member functions used in the functions that are implemented in the file.
Rec. 9 : Use the directive #include "filename.h" for user-prepared include files.
Rec. 10 : Use the directive #include <filename.h> for include files from system libraries.
Rec. 11 : Every implementation should declare a local constant string that describes the file so the UNIX command what can be used to obtain information on the file revision. The string must begin with the characters "@(#)"
Example:
static const char* fileid = "@(#) filename.c, rev. A, EMBOSS project 1998";
Results in the following:
unix: what filename.c filename.c: filename.c, rev. A, EMBOSS project 1998 unix: what file filename.c, rev. A, EMBOSS project 1998
Rec. 12 : Never include other files in a ".i" file.

5. Assigning Names

Rule 10 : The identifier of every globally visible class, enumeration type, type definition, function, constant, variable and macro in a library is to begin with a prefix that is unique for the library.
For Ajax, the prefix will be "aj...". For Nucleus it will be "emb...".
For static data within a class source file, the prefix will be the class abbreviation (examples: str, acd).
Rule 11 : A name that "begins with an uppercase letter" is to appear directly after its prefix. The prefix will begin with an uppercase letter.
Rule 12 : A name that "begins with a lowercase letter" is to appear directly after its prefix. The prefix will begin with a lowercase letter.
Rule 13 : The names of variables, constants and functions are to begin with a lowercase letter.
Examples: ajVersion, ajStrNew, strCount
Rule 14 : The names of typedefs, enums, structs and unions are to begin with an uppercase letter.
This distinguishes them from the builtin types.
Examples: AjoStr, AjpStr
Rule 15 : In names which consist of more than one word, the words are written together and each word that follows the first (or the prefix) begins with an uppercase letter.
Examples: ajStrNew
Rule 16 : Do not use identifiers which begin with one or two underscores ('_' or '__').
Rec. 13 : Do not use typenames that differ only by the use of uppercase and lowercase letters.
Rec. 14 : Names should not include abbreviations that are not generally accepted.
Rec. 15 : A variable with a large scope should have a long name.
Rec. 16 : Choose variable names that suggest the usage.
Rec. 17 : Write code in a way that makes it easy to change the prefix for global identifiers.
Rec. 18 : Encapsulate global variables and constants, enumerated data types and typedefs in a class.
Rec. 19 : Identifier names should not be extremely long, to reduce the risk of name collisions when using tools which truncate long identifiers.

6. Style

There are no rules for programming style, but there are several recommendations.

6.1 Classes

No specific rules or recommendations here, but see section 7 (Classes).

6.2 Functions

Rec. 20 : Always provide the return type of a function explicitly.
Rec. 21 : When declaring functions, the leading parenthesis and the first argument (if any) are to be written on the same line as the function name. If space permits, other arguments and the closing parenthesis may also be written on the same line as the function name. Otherwise, additional arguments are to be written on following line(s) with the closing parenthesis directly after the last argument. The line length should not exceed 79 characters
Rec. 22 : In a function definition, the return type of the function should be written on the same line as the function name.
This differs from the Ellemtel recommendation
Rec. 23 : Leave a space between the function name and the left parenthesis.
This differs from the Ellemtel recommendation

6.3 Compound Statements

Rec. 24 : Braces ("{}") which enclose blocks should start at the end of a line, and end after the last statement.

6.4 Flow Control Statements

Rec. 25 : If a flow control primitive if, else, while, for or do is followed by a single statement, that statement should be indented on the following line. If the statement is empty it should include a comment for clarity.
If a flow control primitive is followed by another primitive, then a block ("{}") must be used around the following primitive.

6.5 Pointers and references

Rec. 26 : The defererence operator '*' should be directly connected with the type name in declarations and definitions.

6.6 Miscellanoeus

Rec. 27 : Do not use spaces around '.' or ->, nor between unary operators and operands.
Rec. 28 : Use the C mode in GNU emacs to format code.

7. Classes

7.1 Considerations Regarding Access Rights

Rule 17 : Never specify global data in a class where data can be hidden and made available through accessor functions.

7.2 Inline Functions

Inline functions are a C++ concept which can be implemented in ANSI C as macro #defines. Using inline functions offers improved performance.

Rec. 29 : Small functions such as accessor functions which return the value of a class member or may be declared inline.
Rec. 30 : Forwarding functions which simply call other functions may be declared inline
Rec. 31 : Constructors and destructors must not be inline.

7.3 Friends

Friends are a C++ concept which can be implemented in ANSI C with the help of accessor functions not declared in the main class header file.

Rec. 32 : Friends of a class may be declared to provide functions that are best kept outside of the class implementation file.
An example could be a set of iterator functions.
Friends can be good if used properly, but the use of many friends can indicate that the modularity of the system design is poor.

7.4 const Member Functions

... Needs some revision once it is clear how the C++ const definitions can be implemented in ANSI C ...

7.5 Constructors and Destructors

Rule 17a : In a class implementation file, the destructor function is to be defined first.
Rule 17b : In a class implementation file, all constructor functions are to be defined immediately after the destructor.
Rule 18 : Where objects are defined from other objects, a copy constructor must be used. Simply copying the pointer will lead inevitably to two destructor calls for the same data object.
Copy constructors can copy pointers provided that reference counting or some other mechanism to avoid destroying in-use data is provided.
Rule 19 : Avoid the use of global objects in constructors and destructors.

7.6 Assignment Operators

Assignment is the C++ implementation of newobject = oldobject and can cause various complications discussed in the Ellemtel document. The implementation of classes in ANSI C avoids these by using explicit function calls to assign objects.

7.7 Operator Overloading

In C++, operator overloading means defining functions to be called when standard operators such as "==" and "!=" are used. In ANSI C overloaded function names are implemented as explicit function calls.

Rec. 33 : When two operators are opposites, such as equals and not equals it may be appropriate to define both as functions. Failure to do so may result in confusion for later users of the library.
This was originally a C++ rule for operator definitions, but can also apply to defining functions for specific operations on a class.

7.8 Member Function Return Types

Rule 20 : A public member function must never return a non-const reference or pointer to member data.
Example:
const char* ajStrStr (AjPStr this) { return this->Ptr; }
In ANSI C, const has the following effects:
- const char* function (...) returns a pointer to data that cannot change. The caller can see the data but the compiler will reject any code that may change the data. The caller must assign the result to a const char* variable or pass as a const char* argument.
- char const * function (...) is the equivalent of the above. The first version is to be preferred, as it can also be used for typedef pointer types.
- char* const function (...) returns a constant pointer. This pointer is fixed and cannot change to point to anything else. it can, however, be safely copied.
- const char* const function (...) returns a constant pointer to constant data. The pointer is fixed and cannot change to point to anything else. As a result, this can only be used to initialize values or passed as a const char* argument.
Rule 22 : A public member function must never return a non-const reference or pointer to data outside an object, unless the object shares the data with other objects.
For an explanation and examples, see above.

7.9 Inheritance

Rec. 34 : Give derived classes access to class type member data by declaring static accessor functions within a common implementation file.

8. Class Templates

Perhaps some comments on the design of related objects will appear here later.

9. Functions

9.1 Function Arguments

Rule 23 : Do not use unspecified function arguments (ellipsis notation) unless speficying a front-end to a standard library function such as printf
Rec. 35 : Avoid functions with many argments
Rec. 36 : If an argument is a pointer type, either check for a NULL pointer or explicitly document what happens if the pointer is not initialized.

Rec. 37 : If an argument is a pointer, declare it as const in the function prototype if the data is unchanged.

AjBool ajStrMatchC (const AjPStr this, const char *text) {
  if (!strcmp (this->Ptr, text))
    return ajTrue;
  else
    return ajFalse;
}

Rec. 38 : Use const pointers rather than call by value for objects.

Call by value involves copying the entire object to the stack. For large objects this can be a very great overhead.

/* assume AjOObject has a data size of 1024 bytes */
/* assume AjPObject is a pointer to AjOObject */

void function (AjOObject object) { /* 1024 bytes */

void function (AjPObject this) {   /* pointer 4-8 bytes */

9.2 Function Overloading

Rec. 39 : When overloading functions (defining a set of functions with similar names and differing argument numbers and types), all variations should have the same semantics (be used for the same purpose).
Rec. 40 : The names of formal arguments to functions should be meaningful and indicate how the argument is used.

9.3 Formal Arguments

Rule 24 : The names of formal arguments to functions are to be specified and are to be the same both in the function definition and in the function declaration (prototype).

9.4 Return Types and Values

Rule 25 : Always specify the return type of a function explicitly.
Functions which return no value must be explicitly declared with return type void.

Rule 26 : A public (globally accessible) function must never return a (non const) pointer to a local variable.

Returning a non const pointer to any local variable would allow that variable to be changed at any time. A const pointer is safe.

Example:

char* myDanger (void) {
  static char buffer[512] = "Hello World";
  return buffer;     /* anyone can change the contents of buffer */
}

const char* mySafe (void) {
  static char buffer[512] = "Hello World";
  return buffer;     /* anyone can see buffer but never change */
}

9.5 Inline Functions

"Inline functions" are a C++ concept where code is written as a function call but implemented as code directly in the source for efficiency. Fortran 77 has a similar capability with "statement functions".

Rule 27 : In ANSI C, inline functions can only be implemented through the #define macro directive. If used, the function will be defined in a header ".h" file. Such functions must also be defined, documented, and commented out, in the corresponding ".c" source file so that they will appear in the correct place in the final documentation.
Rule 28 : A function defined through a #define macro may only refer to each argument once in the definition.
Failure to follow this rule leads to unpredictable results. For example, the following code fails:
#define Square(x) ((x)*(x)) int a=2; int b = Square(a++); /* b = (2 * 3) = 6 */

9.6 Temporary Objects

Rec. 41 : Minimize the number of temporary objects that are created as return values from functions or as arguments to functions.
Where possible, require the caller to specify an object so that the caller can also control when the object is deleted.

9.7 General

Rec. 42 : Avoid long and complex functions.
Long and complex functions are difficult to document and to test. The maximum length of a function should, in general, be about 2 pages of code (120 lines).
Exceptions can be made for long functions with a simple structure, such as a single large switch statement, if breaking up into multiple functions would be more complicated to understand.

10. Constants

Rule 29 : Constants should be defined using static const or enum in preference to #define or using numerical constants.
Constants defined with #define are not recognised by debuggers. If the definition is an expression, the result may be different for different instantiations, depending on the scope of the name.
In C++, constants are created static by default. In ANSI C this must be declared explicitly.
Example:
static const ajBool ajFalse = 0; static const ajBool ajTrue = 1; static enum alpha {a, b, c, d, e, f};
Rule 30 : Avoid the use of numeric values in code. Use symbolic values instead.
It is far better to use a named constant so that it is clear, for example, which instances of "256" should be changed to "512".

11. Variables

Rule 31 : Variables are to be declared with the smallest possible scope.
Rule 32 : Each major variable is to be declared in a separate declaration statement.
Exceptions to this rule include temporary variables and loop variables.
Rule 33 : Every variable that is declared is to be given a value before it is used.
Rule 34 : If possible, always use initialization instead of assignment.

12. Pointers

Rec. 43 : Pointers to pointers should be avoided whenever possible.
Pointers to array objects are much clearer.

Rec. 44 : A function which changes the value of a pointer which is provided as an argument must not also return a copy of the pointer.

This avoids the duplication of pointer values. Typically such functions will return void or a status code while updating the pointer argument.