Each function should be preceded by a block comment prologue that gives a short description of what the function does and (if not clear) how to use it. Discussion of non-trivial design decisions and side-effects is also appropriate. Avoid duplicating information clear from the code.
The function return type should be alone on a line,
(optionally) indented one stop.
``Tabstops'' can be blanks (spaces) inserted by your editor in clumps
of 2, 4, or 8.
Do not default to
int;
if the function does not return a value then it should be given
return type void.
If the value returned requires a long explanation,
it should be given in the prologue;
otherwise it can be on the same line as the return type, tabbed over.
The function name
(and the formal parameter list)
should be alone on a line, in column 1.
Destination (return value) parameters
should generally be first (on the left).
All local declarations and code within the function body
should be tabbed over one stop.
The opening brace of the function body should be alone on a line
beginning in column 1.
Each parameter should be declared (do not default to
int).
In general the role of each variable in the function should be described.
This may either be done in the function comment or, if each declaration
is on its own line, in a comment on that line.
Loop counters called ``i'', string pointers called ``s'',
and integral types called ``c'' and used for characters
are typically excluded.
If a group of functions all have a like parameter or local variable,
it helps to call the repeated variable by the same name in all
functions.
(Conversely, avoid using the same name for different purposes in
related functions.)
Like parameters should also appear in the same place in the various
argument lists.
Comments for parameters and local variables should be tabbed so that they line up underneath each other. Local variable declarations should be separated from the function's statements by a blank line.
Be careful when you use or declare functions that take a variable number of arguments (``varargs''). Always use the ``stdarg.h'' header definitions and do not rely on item order on the stack.
If the function uses any external variables (or functions)
that are not declared globally in the file,
these should have their
own declarations in the function body using the
extern
keyword.
Avoid local declarations that override declarations at higher levels. In particular, local variables should not be redeclared in nested blocks. Although this is valid C, the potential confusion is enough that lint will complain about it when given the -h option.