main-standards - Engineering Standards Manual
Contributed by George Nachman.
Based on the Tcl/Tk Engineering Manual by John K. Ousterhout
This manual is based on the Tcl/Tk Engineering Manual by John K. Ousterhout that is available at http://www.activestate.com/ActiveState. Most of this document is a subset of what his manual specifies, with the goal of being more practical and up-to-date than the original. For example, it is assumed that only an ANSI compiler will be used, whereas the Ousterhout's manual describes conventions that will also work with non-ANSI compilers. The Tcl/Tk Engineering Manual is recommended reading, particularly with respect to the section on code documentation, which is not reproduced here.
Each module will be named nsxxx, where xxx is a short name that describes the module. Each module will have its own directory, and contain at least the following files:
nsxxx.c
Makefile
If a module exports symbols, then a header file by the name of nsxxx.h should also be in that directory.
Use this as a template for module makefiles:
# # nsexample -- # # Example NaviServer module Makefile. # # # NaviServer's location # # Since your module probably doesn't live inside the "naviserver" # directory, you can tell make where to find NaviServer. # #NAVISERVER = /usr/local/ns NAVISERVER = ../naviserver # # File name of binary loadable module # MOD = nsexample.so # # Object files for modules (required with MOD) # MODOBJS = nsexample.o # MODNAME Unique name of module # TCL List of module shared Tcl files # LIBNM Root name of dynamic library (without lib prefix or extension) # LIBOBJS List of library object files (required with LIBNM) # LIBHDRS List of public header files to install (required with module LIBNM) # PGM Name of executable program # PGMOBJS List of program object files (required with PGM) # HDRS Header files which objects depend on # MODLIBS Extra module link libraries # LIBLIBS Extra dynamic library link libraries # PGMLIBS Extra program link libraries # INSTALL Extra install directive(s) # CLEAN Extra clean directive(s) # DESTDIR Root directory for install # # At least one of PGM, MOD, or LIBNM must be defined. For backwards compatibility, # MODOBJS will default to OBJS and MODINST can be used for module install. include $(NSHOME)/include/Makefile.module
Use this as a template for all header files:
/* * The contents of this file are subject to the Mozilla Public License * Version 1.1 (the "License"); you may not use this file except in * compliance with the License. You may obtain a copy of the License at * http://mozilla.org. * * Software distributed under the License is distributed on an "AS IS" * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See * the License for the specific language governing rights and limitations * under the License. * * Alternatively, the contents of this file may be used under the terms * of the GNU General Public License (the "GPL"), in which case the * provisions of GPL are applicable instead of those above. If you wish * to allow use of your version of this file only under the terms of the * GPL and not to allow others to use your version of this file under the * License, indicate your decision by deleting the provisions above and * replace them with the notice and other provisions required by the GPL. * If you do not delete the provisions above, a recipient may use your * version of this file under either the License or the GPL. */ /* * file.h -- * * Description of file. * */ #ifndef FILE_H #define FILE_H /* * The following constants... */ #define ... /* * The following structure defines... */ typedef struct ... /* * Exported functions */ extern ... #endif /* FILE_H */
Header files never contain static symbols.
Each source code file should contain a related set of procedures. The most manageable size for files is usually in the range of 500-2000 lines. Closely related functions should be placed as close together as possible.
API functions (ns_*) come first; exported functions that are not API calls (Ns*) come after those; static functions come last. Logical groups of functions can be separated like this:
/* *========================================================================== * This is where we torque the wingnut on the widget. *========================================================================== */
Use this as a template for all code files:
/* * The contents of this file are subject to the Mozilla Public License * Version 1.1 (the "License"); you may not use this file except in * compliance with the License. You may obtain a copy of the License at * http://mozilla.org/. * * Software distributed under the License is distributed on an "AS IS" * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See * the License for the specific language governing rights and limitations * under the License. * * Alternatively, the contents of this file may be used under the terms * of the GNU General Public License (the "GPL"), in which case the * provisions of GPL are applicable instead of those above. If you wish * to allow use of your version of this file only under the terms of the * GPL and not to allow others to use your version of this file under the * License, indicate your decision by deleting the provisions above and * replace them with the notice and other provisions required by the GPL. * If you do not delete the provisions above, a recipient may use your * version of this file under either the License or the GPL. */ /* * file.c -- * * Description of file. */ #include "file.h" /* * The following constants... */ #define ... /* * The following structure defines... */ typedef struct ... /* * Local functions defined in this file */ static int FunctionName(int x); /* * Static variables defined in this file */ static int nsNumFooBar; /* Number of foobars allocated */ ... /* *========================================================================== * API functions *========================================================================== */ (API function definitions go here) /* *========================================================================== * Exported functions *========================================================================== */ (Exported, non-api functions go here) /* *========================================================================== * Static functions *========================================================================== */ (Static functions go here)
Source files should never contain extern statements; those belong in header files (called file.h in the above template).
Function definitions should follow this template:
/*
*----------------------------------------------------------------------
* FunctionName --
*
* Description of function.
*
* Results:
* This function returns ...
*
* Side effects:
* A new thread will be created.
*
*----------------------------------------------------------------------
*/
static int
FunctionName(int x)
{
...
}
All functions definitions begin on a new page (which is to say they should be preceded by a control-L character). All functions must be typed: use void if the function returns no result. The second line gives the function's name and argument list. If there are many arguments, they should spill onto additional lines as such:
static int
FunctionThatTakesLotsOfParameters(int a, int b, int c, int d, int e,
int f, int g)
{
...
}
The same rule applies to prototypes.
Function parameters may be divided into three categories. In parameters only pass information into the function (either directly or by pointing to information that the function reads). Out parameters point to things in the caller's memory that the function modifies. In-out parameters do both. Below is a set of rules for deciding on the order of parameters to a function:
Parameters should normally appear in the order in, in/out, out, except where overridden by the rules below.
If there is a group of functions, all of which operate on structures of a particular type--such as a hash table--the token for the structure should be the first argument to each of the functions.
When two parameters are the address of a callback function and a context value (or ClientData value) to pass to that function, the function address should appear in the argument list immediately before the context/ClientData.
If a callback function takes a context/ClientData argument (and all callbacks should), the context/ClientData argument should be the first argument to the procedure. Typically the context/ClientData is a pointer to the structure managed by the callback, so this is really the same as rule 2.
In/out parameters should not be used without a very good reason.
Be consistent. Use the same name to refer to the same thing everywhere. For example, in the Tcl implementation the name interp is used consistently for pointers to the user-visible Tcl_Interp structure.
Make sure a function name describes what the function actually does. Will the name make sense out of context?
Sometimes it is appropriate to use one-letter variables, such as a for-loop control variable called i. For anything more complex, a short descriptive name should be used.
Variable names always start with a lowercase letter. Function and type names always start with an uppercase letter.
In multi-word names, the first letter of each word after the first is in uppercase (usually referred to as camel case). Example:
int nsThreadTimeout;
Any name that refers to a pointer ends in Ptr. If it is a pointer to a pointer, then it ends in PtrPtr. Exceptions to this rule include opaque handles for structures (such as ns_ModLogHandle) and char * variables that refer to null-terminated strings. Also, static buffers should not have the Ptr suffix, as in this case:
char buf[32];
It is recommended that the names of variables of type Tcl_Objs end with Obj.
Variables that hold address of procedures should have names ending in Proc, as should typedefs for such variables.
typedef int (Ns_ModuleInitProc) (const char *server, const char *module);
#define macros and constants should be in all uppercase. Underscores separate multiple words (as in NS_TRUE).
Tcl commands are always in all-lowercase.
Public exported functions that are part of the API should begin with Ns_, as in:
extern int Ns_ConnPort(const Ns_Conn *conn)
Functions that are to be used by other files in a module, but are not meant to be called from outside the module, should begin with Ns, as in:
extern void NsDbInit(void);
Global variables that do not have static scope begin with ns, as in:
ns_Cache *nsAdpCachePtr = NULL;
C implementations of Tcl commands should be ending with Cmd, as in:
int NsTclSetObjCmd(ClientData arg, Tcl_Interp *interp, int objc, Tcl_Obj *CONST* objv);
If you use Emacs, the following lisp (which you can put in your .emacs file) will make C-mode do much of the formatting for you (its default behavior is almost correct--this just makes indents be four spaces):
(add-hook 'c-mode-hook (function (lambda () (setq c-basic-offset 4) (setq c-indent-level 4))))
Try to follow these rules:
Indents are four spaces
Code comments occupy full lines, with empty lines before and after, as such:
foo();
/*
* This is a comment.
*/
bar();
Opening curly braces go at the end of a line, except for the beginnings of functions, as such:
if (x == y) {
FooBar();
}
and
static void
FooBar(void)
{
Foo();
}
Always put a blank line after variable definitions:
static void
FooBar(void)
{
int blah;
...
if (blah != 0) {
char *string;
...
}
}
Use curly braces even if you don't have to, such as in if statements that have only statement in the block. There is an exception to this, which is else if clauses which may look like this:
if (!strcmp(cmd, "put")) {
...
} else if (!strcmp(cmd, "get")) {
...
} else if (!strcmp(cmd, "reset")) {
...
} else {
...
}
No line should exceed 79 characters.
Labels are indented four spaces fewer than statements, except when they would touch the left margin, in which case they are indented one space in from the left margin.
Switch statements should look like this:
switch (adPtr->exception) {
case ADP_OK:
exception = "ok";
break;
case ADP_BREAK:
exception = "break";
break;
...
}
Avoid macros except for extremely simple operations. Enclose arguments in parentheses, as well as the entire macro expression:
#define MIN(a,b) (((a) < (b)) ? (a) : (b))
Do not use bit fields
Goto statements may be used as long as they jump to the end of a function that then performs cleanup and returns. They are an excellent way of ensuring that functions have only one exit point. Most other uses of goto are, as usual, looked on with disdain.
Common sense applies when using obscure or confusing parts of the C language. For example, don't do this:
if (++c != NULL) {
foo();
}
Where it is sensible, have only one return statement in each function.
Complex if statements (such as those with three or more expressions) should have newline breaks after the operator separating each expression. In this case, put a newline after the open brace to separate the conditions from the code that follows.
if (foo == bar &&
baz == spoo &&
ns_FooBarBaz() == NS_TRUE) {
...
}
When there are multiple variables defined in a block, the first letter of each variable name should line up, with asterisks running to the left. There should not be multiple variables defined on the same line unless the relationship between them is obvious. Non-obvious variables may be commented to the right.
The leftmost asterisk should begin on the column that is one space after the rightmost character of the longest type name. If there are no pointers, then every variable name should begin on the column that is one space after the rightmost character of the longest type name.
void
Foo(void)
{
int bar;
unsigned int *fooPtr;
int ****extremePtrPtrPtrPtr; /* Just an example! */
...
or
void
Foo(void)
{
int bar;
unsigned int foo;
char baz;
...
Variable initializers should not be anything more complex than a constant; function calls and complicated expressions deserve their own lines of code.
In pointer definitions, be they local variables, global variables, parameters, or static functions prototypes, the asterisk should always make contact with the first character of the symbol. In typecasts, there should be one space between the type name and the asterisk, and parentheses should make contact with both:
static void *Foo(int *fooPtr);
int *fooPtr = (int *) barPtr;
If a function ends with a return statement which is neither the only statement in the function body and is not preceded by a label, an empty line should appear before it:
static int
Foo(void)
{
...
FooBar();
return code;
}
The following conventions are frequently used in NaviServer. They are the recommended way of implementing a behavior.
Configuration parameters should be defined at the top of source files, as such:
#define CONFIG_CACHE "Cache" /* Enable caching in this module? */ #define CONFIG_FOO "Foo" /* What is foo? */ #define DEFAULT_CACHE NS_TRUE /* Caching is on */ #define DEFAULT_FOO "Bar" /* Foo is bar */
C is not PL/I. Write this:
return foo;
not
return (foo);
With very complicated expressions, parentheses are acceptable:
return (sqrt(variance) + foo() / bar() - (MAGIC + getch()) % 99);
Booleans can only have two values: NS_TRUE and NS_FALSE. Using 0 and 1 as boolean values is discouraged. Also avoid using the conventions of
if (foo) { ... }
and
if (!foo) { ... }
rather, say:
if (foo == NS_TRUE) {
...
}
or
if (foo == NS_FALSE) {
...
}
Of course, this only applies to NaviServer APIs and internal boolean values. Respect the wishes of library calls; values from outside code should never be compared with NS_TRUE or NS_FALSE, nor should NS_TRUE or NS_FALSE values ever be passed to outside code.
Explicit checks for null values are usually preferred over implicit checks.
For pointers, use NULL:
if (fooPtr == NULL) {
...
}
or
if (fooPtr != NULL) {
...
}
For characters, use '\0' when checking for equality to zero:
if (char == '\0') {
...
}
For integers, explicitly use 0 when checking for equality to zero:
if (foo == 0) {
...
}