Project coding policy

Project coding policy

Document formatted by vherva at Fri Apr 24 11:23:19 1998 on the host schemestation. This document is produced by the SchemeStation project during the Tik-76.115 course.

1 Purpose

The purpose of this document is to present a policy to control the quality and nature of written code during the SCHEMESTATION project.
Another aim is to make it possible to automatically find description of functions in code and use them as part of the documentation.
Furthermore, the code-browser utility (documentated in Code-Browser Utility) will be used to search and browse the code, which set some minor restrictions.

2 High-level objectives

The coding policy presented here is designed to meet the following objectives:

The coding style must be consistent throughout the project. The author of a piece of code should not be able to be deduced on the basis of the style of the piece only.
Code must be as self-explanatory as possible.
Internal integrity tests in form of checked pre- and post-conditions and other similar mechanisms must be used in order to spot possible faults in the software as early as possible.
Code must be documented. This is aided by a separate utility, that extracts the description of the functions and data structures from the code.
The structure of the code must be modular and easily understood.

3 C coding policy

3.1 Lexical conventions

The language used is ANSI C.
The maximum line length is 78 characters.
Opening and closing curly brackets must be placed on lines of their own.
Every sentence must be put on a line of its own.
Every label must be put on a line of its own.
Indentation style is the default style in Emacs C-mode.
Variable names must be mnemonic, except for standard loop variables etc. The name of a variable must match the regexp [a-z_0-9]+.
typedef and enum must be used in place of #define when possible.
Type names must be mnemonic and match the regexp [A-Z][a-zA-Z]+.
#define'd macro names must match the regexp [A-Z_]+.
An adequate description of each function, its return value and arguments is placed in comment straight before the defination of the function in header file.
Whitespace is required

on the both sides of any binary operator except -> (pointer field dereference) and . (dot);
after a reserved keyword such as if, while etc.; and
after a comma.

Whitespace is not allowed

after the function name in a function call;
before a postfix or after a prefix operator;
before a square bracket;
after an opening parenthesis;
after any unary operator; nor
before or after -> or . (dot).

3.2 Structural conventions

Header files must not create cyclical dependencies.
Every .c file includes whatever it needs.
Every .h includes only what is exactly necessary for the definitions in the file to be self-contained.
Header files must be protected by an #ifdef ... construct.
Declare functions internal to a .c file as ``static'' in order to denote them as such.
Do not use the keyword external before function prototypes in header files; it is obsolete.
Declare functions of zero arguments as foo(void) rather than foo(); foo() means that the arguments are not checked.
Use stdarg, not vararg.
Do not assume that NULL == (void *)0L.
Do not rely on the ambiguous else rule.
Every function should return zero if the function succeeds and a function specific non-zero error code if it fails.
Macros IN, OUT and INOUT (expanding to nothing) must be used to denote input, output and input-output parameters.
All exported functions in a module must be prefixed with a unique identifier derived from the name of the module.

3.3 Other conventions

The specification of any function exported from a module must include suitable pre- and postconditions. These pre- and postconditions must be checked for in the implementation of the function.
Also other critical assertions should be checked using an assert-like macro or something.
A module must be fully usable on the basis of header file information only.

4 Scheme coding policy

4.1 Lexical conventions

Maximum line length is 78 characters.
Use default Emacs indentation.
Don't split lines at the position of |'s in the following examples unless necessary:
(lambda | ...) (define | ...) (proc | arg1 ...)

Do not use underscores in normal variable names.
Write all identifiers in lower case.
An adequate description of each function, its return value and arguments is placed in comment straight before the defination of the function in header file.

4.2 Other conventions

Write R⁴RS compliant code if your code should be runnable outside SCHEMESTATION.
Write functional code when possible; it is more easy to understand.

[Back to the document index]


1 Purpose
	The purpose of this document is to present a policy to control the quality and nature of written code during the SCHEMESTATION project. Another aim is to make it possible to automatically find description of functions in code and use them as part of the documentation. Furthermore, the code-browser utility (documentated in Code-Browser Utility) will be used to search and browse the code, which set some minor restrictions.
2 High-level objectives
	The coding policy presented here is designed to meet the following objectives: The coding style must be consistent throughout the project. The author of a piece of code should not be able to be deduced on the basis of the style of the piece only. Code must be as self-explanatory as possible. Internal integrity tests in form of checked pre- and post-conditions and other similar mechanisms must be used in order to spot possible faults in the software as early as possible. Code must be documented. This is aided by a separate utility, that extracts the description of the functions and data structures from the code. The structure of the code must be modular and easily understood.
3 C coding policy

3.1 Lexical conventions
	The language used is ANSI C. The maximum line length is 78 characters. Opening and closing curly brackets must be placed on lines of their own. Every sentence must be put on a line of its own. Every label must be put on a line of its own. Indentation style is the default style in Emacs C-mode. Variable names must be mnemonic, except for standard loop variables etc. The name of a variable must match the regexp `[a-z_0-9]+`. `typedef` and `enum` must be used in place of `#define` when possible. Type names must be mnemonic and match the regexp `[A-Z][a-zA-Z]+`. `#define`'d macro names must match the regexp `[A-Z_]+`. An adequate description of each function, its return value and arguments is placed in comment straight before the defination of the function in header file. Whitespace is required on the both sides of any binary operator except `->` (pointer field dereference) and `.` (dot); after a reserved keyword such as `if`, `while` etc.; and after a comma. Whitespace is not allowed after the function name in a function call; before a postfix or after a prefix operator; before a square bracket; after an opening parenthesis; after any unary operator; nor before or after `->` or `.` (dot).
3.2 Structural conventions
	Header files must not create cyclical dependencies. Every `.c` file includes whatever it needs. Every `.h` includes only what is exactly necessary for the definitions in the file to be self-contained. Header files must be protected by an `#ifdef ...` construct. Declare functions internal to a `.c` file as ``static'' in order to denote them as such. Do not use the keyword `external` before function prototypes in header files; it is obsolete. Declare functions of zero arguments as `foo(void)` rather than `foo()`; `foo()` means that the arguments are not checked. Use stdarg, not vararg. Do not assume that `NULL == (void *)0L`. Do not rely on the ambiguous else rule. Every function should return zero if the function succeeds and a function specific non-zero error code if it fails. Macros `IN`, `OUT` and `INOUT` (expanding to nothing) must be used to denote input, output and input-output parameters. All exported functions in a module must be prefixed with a unique identifier derived from the name of the module.
3.3 Other conventions
	The specification of any function exported from a module must include suitable pre- and postconditions. These pre- and postconditions must be checked for in the implementation of the function. Also other critical assertions should be checked using an `assert`-like macro or something. A module must be fully usable on the basis of header file information only.
4 Scheme coding policy

4.1 Lexical conventions
	Maximum line length is 78 characters. Use default Emacs indentation. Don't split lines at the position of `\|`'s in the following examples unless necessary: (lambda \| ...) (define \| ...) (proc \| arg1 ...) Do not use underscores in normal variable names. Write all identifiers in lower case. An adequate description of each function, its return value and arguments is placed in comment straight before the defination of the function in header file.
4.2 Other conventions
	Write R⁴RS compliant code if your code should be runnable outside SCHEMESTATION. Write functional code when possible; it is more easy to understand.