Coding Standards¶

Heinz Wrobel's C coding standards for Amiga development (DevInfo/Style/CodingStandards). These are project-level conventions; the single overriding rule is "BE CONSISTENT — READABILITY COUNTS."

The zeroeth law¶

Agree on coding rules before the project starts, write them down, revise as a group, and document the reasons for every change.

Formatting / braces¶

Tabs. "Disk tabs" must always be 8 spaces — it is the only tab width that preserves source alignment across all editors and OSes. Use a separate, smaller "screen tab" display setting (4 recommended) that the editor converts to/from 8-space disk tabs on load/save. Disable automatic tab conversion if anyone else will touch the sources, or revision control diffs become meaningless noise.
Comment the closing brace. Never write a bare }; write } /* if */, } /* switch */, } /* function_foo */. Do the same for #endif. When 10+ closing braces stack, this is what makes them matchable.
Vertically aligned braces (not K&R style) — matching braces in one column are easier for the eye.
Always use braces, even for a single statement, so later edits can't silently break an else or dangling-statement dependency.
Do not fake other languages. Redefining {/} as BEGIN/END via the preprocessor is explicitly called a misuse; use the language as defined.
Limit function size to roughly two screenfuls; split into subfunctions beyond that.
Limit file size to "a few hundred lines"; 1k lines is the absolute ceiling. Modularity via the linker is a feature.
Separate functions with a plain rule line /*----...----*/; avoid "bold" lines made of asterisks (they lose their line character on some displays).
Each source file gets a standard header (e.g. an RCS $Id$ block) and a footer /* End of Text */.

Using the language and compiler¶

ANSI C prototypes, not K&R. The compiler is your friend; stricter checking catches bugs.
Run the compiler in its strictest error-checking mode. "ERRORS AND WARNINGS ARE NOT ACCEPTABLE!"
Read your compiler's "implementation-defined behaviour" section before starting; keep a copy of the C standard and a reference like P.J. Plauger's The Standard C Library on hand.
Stay with standards. Use the ANSI library for portable C, the OS API for Amiga-specific work; avoid mixing the two arbitrarily, and avoid compiler/HW-specific extensions if portability matters. Watch for \r\n vs \n and ISO-character mangling differences; binary and text I/O differ in the ANSI library.
Isolate non-portable code.
Use const and volatile. const materially improves the compiler's diagnostics (some compilers emit worse code with them — in that case #define const to nothing for production builds only).
static for anything not needed externally — helps the linker, modularity, and the black-box principle.
Use the preprocessor carefully. Hidden side effects in macros are not always diagnosed; don't overdo it.
For self-contained modules (e.g. a time-conversion routine), add a #ifdef TEST ... main() ... #endif test harness in the same source file.
The linker is your friend; use make, but keep a fallback to a standard make scheme because make dialects vary.
C is most efficient with pointers; teams must have a firm understanding of pointers or be taught first.
Check every function result that can fail (memory allocation especially). Assume the negative case. "It will hardly ever be a performance hit."

Debugging C¶

Check for NULL pointers and pointer overruns.
C strings are one byte longer than their contents (trailing NUL).
Check for a missing closing */ — a lost line of code can hide there.
For a hiding bug, have the author walk through the logic line-by-line, including limits and exceptions, to a teammate not involved in that code.

Code management¶

Use a revision control system (RCS, CVS, SCCS). Put an $Id$ in every source file. Never use expanding $Log$ keywords — they duplicate the repository and clutter diffs.
Mark stable revisions; no uncommitted work files left at the end of a working day.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search