File: standards.html

package info (click to toggle)
aolserver4 4.0.10-7
links: PTS
area: main
in suites: etch, etch-m68k
size: 11,188 kB
ctags: 14,155
sloc: ansic: 39,138; tcl: 5,256; sh: 2,939; makefile: 318; php: 13
file content (784 lines) | stat: -rw-r--r-- 19,782 bytes
parent folder | download | duplicates (8)
<html>
<head>
<title>AOLserver</title>
</head>
<body>

<h1>Engineering Standards Manual</h1>

<p>
<small>
$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tech/standards.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
</small>
<p>

Contributed by George Nachman.
<BR>
Based on the Tcl/Tk Engineering Manual by John K. Ousterhout
<P>

<h2>Introduction</h2>

This manual is based on the <I>Tcl/Tk Engineering Manual</I> by John
K. Ousterhout that is available at <a href=http://www.activestate.com/
target=_newwindow>ActiveState</a>. 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
<I>Tcl/Tk Engineering Manual</I> is still recommended reading,
particularly with respect to the section on code documentation, which
is not reproduced here.

<h2>Table of Contents</h2>

<UL>
<LI><a href="#overall">   Overall structure</a></LI>
<LI><a href="#makefile">  Makefile structure</a></LI>
<LI><a href="#header">    Header file structure</a></LI>
<LI><a href="#code">      Code file structure</a></LI>
<LI><a href="#function">  Function definitions</a></LI>
<LI><a href="#parameter"> Parameter order</a></LI>
<LI><a href="#naming">    Naming conventions</a></LI>
<LI><a href="#syntax">    Basic syntax rules</a></LI>
<LI><a href="#names">     Function names contain meaning</a></LI>
<LI><a href="#low">       Low-level coding conventions</a></LI>
<LI><a href="#idioms">    Idioms, Canonical Forms, and Recommended Practices</a></LI>
</UL>
</B>

<P>
<h2><A NAME="overall">Overall Structure</a></h2>

Each module will be named ns<I>xxx</I>, where <I>xxx</I> is a short
name that describes the module. Each module will have its own
directory, and contain at least the following files:

<ul>
<li>ns<i>xxx</i>.c</li>
<li>Makefile</li>
</ul>

<P> If a module exports symbols, then a header file by the name of
ns<I>xxx</I>.h should also be in that directory.
<P>

<h2><A NAME="makefile">Makefile Structure</h2>

Use this as a template for module makefiles:

<pre>
#
# (dollar-sign)Header: (dollar-sign)
#
# nsexample --
#
#      Example AOLserver module Makefile.
#

#
# AOLserver's location
#
#  Since your module probably doesn't live inside the "aolserver"
#  directory, you can tell make where to find aolserver.
#
#NSHOME   =  /home/user/cvs/aolserver
NSHOME   =  ../aolserver

#
# Module name
#
MOD      =  nsexample.so

#
# Objects to build
#
OBJS     =  nsexample.o

#
# Header files in THIS directory (included with your module)
#
HDRS     =  

#
# Extra libraries required by your module (-L and -l go here)
#
MODLIBS  =  

#
# Compiler flags required by your module (-I for external headers goes here)
#
CFLAGS   =  


include  $(NSHOME)/include/Makefile.module

</pre>

<h2><A NAME="header">Header file structure</a></h2>

Use this as a template for all header files:

<PRE>
/*
 * The contents of this file are subject to the AOLserver 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://aolserver.com/.
 *
 * 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.
 *
 * The Original Code is AOLserver Code and related documentation
 * distributed by AOL.
 * 
 * The Initial Developer of the Original Code is America Online,
 * Inc. Portions created by AOL are Copyright (C) 1999 America Online,
 * Inc. All Rights Reserved.
 *
 * 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

static const char
*RCSID_FILE_H = "(dollar-sign)Header: (dollar-sign), compiled: " __DATE__;

/*
 * The following constants...
 */

#define ...

/*
 * The following structure defines...
 */

typedef struct ...

/*
 * Exported functions
 */

extern ...

#endif /* FILE_H */
</PRE>

<P>

Header files never contain static symbols.


<h2><A NAME="code">Code File Structure</a></h2>

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.

<P>

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:

<P>

<PRE>
/*
 *==========================================================================
 * This is where we torque the wingnut on the widget.
 *==========================================================================
 */
</PRE>

<P>

Use this as a template for all code files:

<PRE>
/*
 * The contents of this file are subject to the AOLserver 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://aolserver.com/.
 *
 * 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.
 *
 * The Original Code is AOLserver Code and related documentation
 * distributed by AOL.
 * 
 * The Initial Developer of the Original Code is America Online,
 * Inc. Portions created by AOL are Copyright (C) 1999 America Online,
 * Inc. All Rights Reserved.
 *
 * 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.
 */
 
static const char
*RCSID = "(dollar-sign)Header: (dollar-sign), compiled: " __DATE__ " " __TIME__;

#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)
</PRE>

<P>

Source files should never contain extern statements; those belong in
header files (called file.h in the above template).

<h2><A NAME="function">Function definitions</a></h2>

Function definitions should follow this template:

<PRE>
/*
 *----------------------------------------------------------------------
 * FunctionName -
 *
 * 	Description of function.
 *
 * Results:
 *	This function returns ...
 *
 * Side effects:
 *	A new thread will be created.
 *
 *----------------------------------------------------------------------
 */

static int
FunctionName(int x)
{
	...
}
</PRE>
<P>
All functions definitions begin on a new page (which is to say they
should be preceeded 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:

<PRE>
static int
FunctionThatTakesLotsOfParameters(int a, int b, int c, int d, int e, 
                                  int f, int g)
{
	...
}
</PRE>

<P>
The same rule applies to prototypes.

<h2><a><A NAME="parameter">Parameter order</a></h2>

Function parameters may be divided into three categories. <I>In</I>
parameters only pass information into the function (either directly or
by pointing to information that the function reads). <I>Out</I>
parameters point to things in the caller's memory that the function
modifies. <I>In-out</I> parameters do both. Below is a set of rules
for deciding on the order of parameters to a function:

<OL>

<LI>Parameters should normally appear in the order in, in/out, out,
except where overridden by the rules below.</LI>

<LI>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.
</LI>

<LI>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.</LI>

<LI>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.</LI>

<LI>In/out parameters should not be used without a <I>very </I>good
reason.</LI>

</OL>

<h2><A NAME="naming">Naming Conventions</a></h2>

<OL>

<LI>Be consistent. Use the same name to refer to the same thing
everywhere. For example, in the Tcl implementation the name
<I>interp</I> is used consistently for pointers to the user-visible
Tcl_Interp structure.</LI>

<LI>Make sure a function name describes what the function actually
does. Will the name make sense out of context?</LI>

<LI>Sometimes it is appropriate to use one-letter variables, such as a
for-loop control variable called <I>i</I>. For anything more complex,
a short descriptive name should be used.</LI>

</OL>

<h2><A NAME="syntax">Basic Syntax Rules</a></h2>

<OL>

<LI>Variable names always start with a lowercase letter. Function and
type names always start with an uppercase letter.</LI>

<LI>In multi-word names, the first letter of each word after the first
is in uppercase. For example,
<br>

<tt>int nsThreadTimeout;</tt>

</LI>

<LI>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:

<br>

<tt>char buf[32];</tt>

</LI>

<LI>Variables that hold address of procedures should have names ending
in Proc, as should typedefs for such variables.<br> <tt>typedef int
(Ns_OpProc) (void *argPtr, Ns_Conn *connPtr) Ns_OpProc
*opProc;</tt></LI>


<LI><tt>#define</tt> macros and constants should be in all
uppercase. Underscores separate multiple words (as in NS_TRUE).</LI>

<LI>Tcl commands are always in all-lowercase.</LI>

</OL>

<h2><A NAME="names">Function names contain meaning</a></h2>

Public exported functions that are part of the API should begin with
Ns_, as in:
<PRE>extern int Ns_ConnPort(Ns_Conn *conn);</PRE>
<P>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:
<PRE>extern void NsDbInit(void);</PRE>
<P>Global variables that do <I>not</I> have static scope begin with ns, as in:
<PRE>Ns_Cache *nsAdpCachePtr = NULL;</PRE>
<P>C implementations of Tcl commands should be static functions ending
with Cmd, as in:
<PRE>static int RegisterTagCmd(ClientData ignored, Tcl_Interp *interp,
                          int argc, char **argv);
</PRE>

<h2><A NAME="low">Low-level coding conventions</a></h2>

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):
<PRE>(add-hook 'c-mode-hook
	(function (lambda ()
		(setq c-basic-offset 4)
		(setq c-indent-level 4))))
</PRE>

<UL>
<LI>Indents are four spaces
</LI>
<LI>Code comments occupy full lines, with empty lines before and
after, as such:
</LI>

<DIR>

<PRE>foo();

/*
 * This is a comment.
 */

bar();
</PRE>
</DIR>


<LI>Opening curly braces go at the end of a line, except for the
beginnings of functions, as such:
</LI>
<DIR>

<PRE>

   if (x == y) {
       FooBar();
   }

<P>and
<PRE>
   static void
   FooBar(void)
   {
      Foo();
   }

</DIR>

<LI>Always put a blank line after variable definitions:
<DIR><PRE>
static void
FooBar(void)
{
    int blah;

    ...
    if (blah != 0) {
        char *string;

	...
    }
}   
</PRE></DIR></LI>

<LI>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:
</LI>

<DIR><PRE>

if (!strcmp(cmd, &quot;put&quot;)) {
    ...
} else if (!strcmp(cmd, &quot;get&quot;)) {
    ...
} else if (!strcmp(cmd, &quot;reset&quot;)) {
    ... 
} else {
    ...
}
</PRE></DIR>

<LI>No line should exceed 79 characters. The only exception to this is CVS
headers because they have an external dependency.
</LI>
<LI>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.
</LI>
<LI>Switch statements should look like this:
</LI>

<DIR><PRE>

switch (adPtr-&gt;exception) {
case ADP_OK:
    exception = &quot;ok&quot;;
    break;
case ADP_BREAK:
    exception = &quot;break&quot;;
    break;
....
}
</PRE></DIR>

<LI>Avoid macros except for extremely simple operations. Enclose
arguments in parentheses, as well as the entire macro
expression:
</LI>

<DIR><PRE>
#define MIN(a,b) (((a) &lt; (b)) ? (a) : (b))
</PRE></DIR>

<LI>Do not use bit fields
</LI>
<LI>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.
</LI>
<LI>Common sense applies when using obscure or confusing parts of the
C language. For example, don't do this:
<P>

<DIR><PRE>
if (++c != NULL) {
    foo();
}
</PRE></DIR>

<LI>Where it is sensible, have only one return statement in each function.
</LI>
<LI>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 two newlines after the open brace to separate the
conditions from the code that follows.
</LI>

<DIR><PRE>
if (foo == bar &&
    baz == spoo &&
    Ns_FooBarBaz() == NS_TRUE) {

    ...
}
</PRE></DIR>

<LI>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.
<p>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.

<DIR><PRE>
void
Foo(void)
{
    int              bar;
    unsigned int    *fooPtr;
    int          ****extremePtrPtrPtrPtr;  /* Just an example! */     

    ...
</PRE></DIR>
or
<DIR><PRE>
void
Foo(void)
{
    int          bar;
    unsigned int foo;
    char         baz;
    
    ...
</PRE></DIR>

Variable initializers should not be anything more complex than a constant;
function calls and complicated expressions deserve their own lines of code.


</LI>
<LI>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 asterik, and parentheses should
make contact with both:
<DIR><PRE>
static void *Foo(int *fooPtr);
int *fooPtr = (int *) barPtr;
</PRE></DIR></LI>
<LI>If a function ends with a return statement which is neither the only
statement in the function body and is not preceeded by a label, an empty
line should appear before it:
<DIR><PRE>
static int
Foo(void)
{
    ...
    FooBar();

    return code;
}    
</UL>

<P>
<h2><A NAME="idioms">Idioms, Canonical Forms, and Recommended Practices</a></h2>

The following conventions are frequently used in AOLserver. They
are the recommended way of implementing a behavior.
<UL>
<LI>Configuration parameters should be defined at the top of source files, as
such:

<DIR><PRE>
#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 */
</PRE></DIR>
</LI>

<LI>C is not PL/I. Write this:

<DIR><PRE>
return foo;
</PRE></DIR>

not

<DIR><PRE>
return (foo);
</PRE></DIR>

With very complicated expressions, parentheses are acceptable:

<DIR><PRE>
return (sqrt(variance) + foo() / bar() - (MAGIC + getch()) % 99);
</PRE></DIR>

<LI>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 <code>if (foo)</code> and <code>if (!foo)</code>; rather, say:

<DIR><PRE>
if (foo == NS_TRUE) {
    ...
}
</PRE></DIR>

or    

<DIR><PRE>
if (foo == NS_FALSE) {
    ...
}
</PRE></DIR>

Of course, this only applies to AOLserver 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.
</LI>

<LI>Explicit checks for 0 values are usually preferred over implicit checks.
<P>
For pointers, use <code>NULL</code>:

<DIR><PRE>
if (fooPtr == NULL) {
    ...
}    
</PRE></DIR>

or

<DIR><PRE>
if (fooPtr != NULL) {
    ...
}    
</PRE></DIR>

For characters, use <code>'\0'</code> when checking for equality to zero:

<DIR><PRE>
if (*ch == '\0') {
    ...
}
</PRE></DIR>

For integers, explicitly use 0 when checking for equality to zero:

<DIR><PRE>
if (foo == 0) {
    ...
}
</PRE></DIR>

</LI>
</UL>

<p>

</body>
</html>