Engineering Standards Manual

$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tech/standards.html,v 1.2 2002/09/26 19:51:33 kriston Exp $

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

Introduction

Table of Contents

• Overall structure
• Makefile structure
• Header file structure
• Code file structure
• Function definitions
• Parameter order
• Naming conventions
• Basic syntax rules
• Function names contain meaning
• Low-level coding conventions
• Idioms, Canonical Forms, and Recommended Practices

Overall Structure

• nsxxx.c
• Makefile

If a module exports symbols, then a header file by the name of nsxxx.h should also be in that directory.

Makefile Structure

#
# (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

Header file structure

/*
 * 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 */

Header files never contain static symbols.

Code File Structure

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 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)

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

Function definitions

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

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

The same rule applies to prototypes.

Parameter order

1. Parameters should normally appear in the order in, in/out, out, except where overridden by the rules below.
2. 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.
3. 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.
4. 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.
5. In/out parameters should not be used without a very good reason.

Naming Conventions

1. 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.
2. Make sure a function name describes what the function actually does. Will the name make sense out of context?
3. 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.

Basic Syntax Rules

1. Variable names always start with a lowercase letter. Function and type names always start with an uppercase letter.
2. In multi-word names, the first letter of each word after the first is in uppercase. For example,
   int nsThreadTimeout;
3. 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];
4. Variables that hold address of procedures should have names ending in Proc, as should typedefs for such variables.
   typedef int (Ns_OpProc) (void *argPtr, Ns_Conn *connPtr) Ns_OpProc *opProc;
5. #define macros and constants should be in all uppercase. Underscores separate multiple words (as in NS_TRUE).
6. Tcl commands are always in all-lowercase.

Function names contain meaning

extern int Ns_ConnPort(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 static functions ending with Cmd, as in:

static int RegisterTagCmd(ClientData ignored, Tcl_Interp *interp,
                          int argc, char **argv);

Low-level coding conventions

(add-hook 'c-mode-hook
	(function (lambda ()
		(setq c-basic-offset 4)
		(setq c-indent-level 4))))

• 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. The only exception to this is CVS headers because they have an external dependency.
• 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 two newlines 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 asterik, 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 preceeded by a label, an empty line should appear before it:

  static int
  Foo(void)
  {
      ...
      FooBar();
  
      return code;
  }    
  

Idioms, Canonical Forms, and Recommended Practices

• 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 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.
• Explicit checks for 0 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 (*ch == '\0') {
      ...
  }
  

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

  if (foo == 0) {
      ...
  }