API style guide

• Section menu
  • Top
  • API header text layout
  • Indentation
    • Issues
    • Examples
  • Identifier construction
    • Issues
    • Examples
  • Pragmatics
    • Issues
    • Examples
  • Semantics (or what?)
    • Issues
    • Examples
  • Appendix: API mail, news and web style
  • Version history

API header text layout

• Logical tabs by 2, 4 columns or by 8 logical columns.
• Physical tabs should not be present, make sure in Visual Studio that tabs are expanded to spaces. I would accept physical tabs only if they expand to 8 columns as in UNIX, but then it is much preferable to have only spaces.
• Begin global identifier declarations or definitions at the leftmost column; linkage before storage class before type.
• Indent identifiers by 24 columns. Continuations in parameter lists indented with respect to that.
• Preferably put parameter list closing braces after the last parameters, rather than on the next line.
• Lines should not be longer than 80 characters.
• Documentation can and usually be provided using JavaDoc style comments (but usually avoid putting HTML tags in them) ready to be processed by Doxygen which is our chosen embedded documentation processor.
• One line API item Doxygen comments should be in the header file; the longer version should be in the source file.

Example:

typedef float           CxReal;

struct CxPair
{
  void                  *data1;
  void                  *data2;
  void                  **aux;
};

typedef unsigned        (*CxIntersectTest)(CxOverlapInfoID info,
                          CxReal tm1[],void *data1,
                          CxReal tm2[],void *data2);

void                    CxObjectParamsGet(CxWorldID world,CxObjectID object);

unsigned                CxObjectUpdate(CxWorldID world,CxObjectID object,
                          CxReal bounds[]);

Indentation

• Any common indentation style, that is K&R, BSD or GNU are acceptable.
• Indentation steps of 2, 4 or 8 columns.
• Continuation lines to be indented by the indentation step, but argument or parameter lists that may continue at the opening parenthesis column.
• Comments should be either in GNU or UNIX V7 format, or in javadoc-like format (documentation comments starts with /**, tags embedded in them start with @) if they are documentation blocks, rather than mere comments, for use with Doxygen.
• I really dislike making comments stand out using rows/boxes of asterisks or dashes or equal signs.

/* Indentation GNU style with GNU style comment.
   GNU style is as a rule step 2. */

typedef struct MdBody   MdBody;
typedef struct MdBody   *MdBodyID;

MdBodyID MdBodyCreate()
{
  MdBody *b = (MdBody *) (*MemoryAPI.create)(sizeof (MdBody));

  if (b != 0)
    {
      (*MemoryAPI.incRef)(b);
      {
        b->mass = 0.0f;
        b->density = 1.0;
        MmVec3Set(b->currentPos,0.0f,0.0f,0.0f);
      }
      (*MemoryAPI.decRef)(b);
    }

  return b;
}

/*
    Indentation K&R style with UNIX V7 comment style.
    K&R style is as a rule step 4 (yes, from edition 2).
*/

MdBodyID MdBodyCreate()
{
   MdBody *b = (MdBody *) (*MemoryAPI.create)(sizeof (MdBody));

   if (b != 0) {
       (*MemoryAPI.incRef)(b);
       b->mass = 0.0f;
       b->density = 1.0;
       MmVec3Set(b->currentPos,0.0f,0.0f,0.0f);
       (*MemoryAPI.decRef)(b);
   }

   return b;
}

/**
 * Create a new body.
 * The newly created bdy is allocated using the memory manager API,
 * and its fields are initialised to some default @e neutral values.
 * @return The ID of a newly created, initialised body.
 * @internal 
 * Indentation BSD style (with javadoc style comment).
 * BSD style is as a rule step 8.
 */

MdBodyID
MdBodyCreate()
{
        MdBody         *b = (MdBody *) (*MemoryAPI.create)(sizeof (MdBody));

        if (b == 0)
                abort();
        else
        {
                (*MemoryAPI.incRef)(b);
                b->mass = 0.0f;
                b->density = 1.0;
                MmVec3Set(b->currentPos,0.0f,0.0f,0.0f);
                (*MemoryAPI.decRef)(b);
        }

        return b;
}

Identifier construction

The names of header files should be built in the same way as identifiers. In effect the name of an header file should be the common prefix of the thingies declared in it.

• Identifiers use the CMU/Smalltalk convention ("SomeLongName"), instead of the BSD ("some_long_name") one.
• Globally visible names (variables, functions, constant variables) begin with an upper case letter.
• Locally visible names (e.g. members, function or block local variables) with a lower case letter.
• Macro names, whether functions or not, have the last component in upper case. Inline functions should also have the last component in upper case, if a non inline version is also provided.
• Names are prefixed with a package prefix followed by a class name prefix (possibly several) followed by operation name.
• Currently defined package prefixes are:

  Prefix	Library
  Me	Utility libraries.
  Mdt	MathEngine Dynamics Toolkit (aka KEA)
  Mcd	MathEngine Collision Detection (aka Collision Lite)

• The components of a name are such that the name of an operation is a prefix to the type of the operand, that is BodySetPosition rather than BodyPositionSet.
• Each object type name should be a typedef for the corresponding struct name, with the same name.
• Common operation names should be like:

  void PkgInit(....)

  Package initialisation.

  void PkgUpdate(....),

  Update package state.

  void PkgTerm()

  Package cleanup.

  PkgTypeID PkgCreateType(....)

  Allocate and initialize a new instance of a type.

  void PkgDestroyType(PkgTypeID)

  Deinitizialize and deallocate an instance of a type.

  FieldType PkgTypeGetField(PkgTypeID)

  Get the value of a field.

  void PkgTypeSetField(PkgTypeID,FieldType)

  Set the value of a field.

/* Global name, so uppercase, also because it begins with
   package prefix. */
struct MuMemoryAPI
{
  void                  *(*create)(size_t bytes,...);
  void                  (*incRef)(void *);
  void                  (*decRef)(void *);
  void                  (*destroy)(void *);
};

/* Arguably this is global, because it is file global.
   Local is local to a function, or a struct. */
static struct MuMemoryAPI  MemoryAPI;

static void MuMemoryNoop(void *)
{
  continue;
}

typedef struct MdBody   MdBody;
typedef struct MdBody   *MdBodyID;

struct MdBody
{
  /* field names are local to the 'struct' and thus
     begin with a lower case letter. */
  float                 mass;
  float                 density;
  MmVector3             currentPos;
};

/* Method name in upper case ("SETMASS"), this is a macro */

#define MdBodySETMASS(b,m)      ((b)->mass = (m))

int main()
{
  MemoryAPI.create = malloc;
  MemoryAPI.destroy = free;
  MemoryAPI.incRef = noop;
  MemoryAPI.decRef = noop;
}

MdBodyID MdBodyCreate()
{
  MdBody *b = (MdBody *) (*MemoryAPI.create)(sizeof (MdBody));

  (*MemoryAPI.incRef)(b);
  {
    b->mass = 0.0f;
    b->density = 1.0;
    MmVec3Set(b->currentPos,0.0f,0.0f,0.0f);
  }
  (*MemoryAPI.decRef)(b);

  return b;
}

void MdBodyDestroy(MdBodyID b)
{
  (*MemoryAPI.destroy)((void *) b);
}

Pragmatics

• APIs should be in ANSI C, not C++.
• Parameters should be named in functions declarations.
• Parameters should be generic-to-specific in left-to-right order. Thus for example the object being operated upon should be the first parameter. In other words, if one were to partially apply functions, one would bind first the rightmost parameters.
• Whenever a parameter is used in a macro body surround it with round parenthesises.
• If a macro body is a single statement, surround it with round parenthesises. If it contains multiple statements, sourround it with the customary 'do { and } while (0) sequences.
• Don't leave functions or inlines without an explicit return type, use void.
• As a rule API functions should be functions. If API functions are macros/inlines, usually a non inline function version should also be provided.
• In exceptional cases, for demonstrated speed reasons, API functions may be macros/inlines that refer to fields in struct definitions, which may then appear in the API headers.
  Usually however this should be arranged such that there is a header with the struct definition and another (which includes the first) with the macro that is actually the published API.
• Given that our target development architecture compilers all support inline functions (GNU C, VS6), instead of macros we can almost always use them, especially with Qua functions.
• All include files should be protected by the customary #ifndef, #define, #endif sequence against multiple inclusion.
• Each source file, whether header or C, should include only the header files on which is depends directly.
• Header files should be listed general-to-specific in top-to-bottom order. Thus all system header files (usually those referred to in angular brackets) should be listed first, then the library local ones, then last the header file for the C file.

/*
  It is arguable, but the order of parameters here is 'to','from','n'
  because MemoryCopyDouble(void *to,void *from [, 8]) is useful, and
  MemoryZeroPage(void *to [,pageOfZeros,4096]) is too, thus we conclude
  that 'n' is more specific than 'from' which is more specific than
  'to'. As 'to' is the memory object being operated upon, so it should
  come first indeed; in effect "MemoryCopy" is a misnomer and the
  function should be called "MemorySet".
*/

void                    MemoryCopy(void *to,void *from,unsigned n);

#ifndef THING_HXX
#define THING_HXX
class Thing
{
  float                 p1;
public:
  float                 m1;
  void                  f1();
};
#endif

#include "Thing.hxx"

extern "C" float ThingGetM1(const ThingID b)             { return b->m1; }
extern "C" void  ThingSetM1(ThingID b,const float v)     { b->m1 = v; }
extern "C" void  ThingF1(ThingID b)                      { b->f1(); }

#ifndef THINGPUB_H
#define THINGPUB_H
struct ThingPub
{
  float                 m1;
};
#endif

#ifndef THING_HXX
#define THING_HXX

#include <ThingPub.h>

class Thing: ThingPub
{
  float                 p1;
public:
  void                  f1();
};
#endif

#ifndef THING_H
#define THING_H

/*
  Including this allows the user to use directly the
  fields of the 'struct' if necessary
*/
#include <ThingPub.h>

typedef struct ThingPub Thing;

/*
  Otherwise the user can use the inline functions or
  macros if s/he is wise.
*/
#if (__GNUC__) || (_MSC_VER)
  static __inline float ThingGetM1(const ThingID t)           { return t->m1; }
  static __inline void ThingSetM1(ThingID t,const float v)    { t->m1 = v; }
#else
# define ThingGetM1(t)                                ((t)->m1)
# define ThingSetM1(t,v)                              ((void) ((t)->m1 = (v)))#endif

#endif

Semantics (or what?)

• const should be used whenever meaningful.
• Objects references should be opaque but implemented as a pointer type.
• The API might provide a way to reveal the actual type of an object reference, with a function named like MdBodyIDtoPtr, but this can as a rule only be done in an implementation and platform dependent way, so it must be protected by an #if or #ifdef.
• Access to properties of objects should usually be by using accessor (e.g. GetField) or mutator (e.g. SetField) functions, or macros/inlines (e.g. GETFIELD and SETFIELD).
  Usually both functions and macros/inlines should be defined, because in some cases speed is important, in some others code compactness.
• In the particular case of KEA version 1, and in other cases where explicit permission has been given by Bob for good reasons, the fields of an objects type can be documented, for direct access by the user, but accessor/mutator functions and/or macros/inlines must still be provided.
  It should also be noted that documenting direct access to the memory layout of an object can result in significant slow downs on many common architectures, as copying is required to convert between documented and optimised memory layouts.
• When providing a function (or macro/inline) to operate on one thingie, consider providing another that does the same thing on an array of thingies, if the work the function does not take a lot of time (where thingie may be an object or a field of an object).
• All data types should be typedefs, in particular vector types, as we want to make sure that all vectors and vector elements are integrally aligned on four floats (128 bit) boundaries, at least optionally, for machines that support 4-way SIMD code.
• In the implementation, try to make it easy to switch the layout of collections of data structures to contiguous arrays to make vectorisation easier.
  Consider whether a vector of records should be serial (an array of structs, all fields for the same record contiguous in memory) or parallel (a struct of arrays, all values of the same field contiguous in memory).
• Inheritance can be modeled by flattening out the API of each class.
• Inheritance can be modeled by providing a Qua function or inline that turns an ID to an instance of a derived class into an ID to the instance of the base class embedded in it.
  This function may actually be a macro (but then some type checking is lost).

#if (MeArchSIMD)
  typedef float         MeVector3[4];
#else
  typedef float         MeVector3[3];
#endif

typedef struct MdBody   *MdBodyID;

#define MdBodyMAX       800

static struct MdBody    MdBodies[800];

/* Converting an ID to a pointer is easy */
#define MdBodyIDTOPTR(b) (b)

void                    MdBodyMove(MdBodyID b,MeVector3 pos);
void                    MdBodyMoveN(MdBodyID b[],MeVector3 pos[],
                          unsigned n);

/*
  Undocumented internal representation.
*/
#define MkBodyCLUSTLOG  2
#define MkBodyCLUSTMASK 3

struct MkBodyClust
{
  float                 mass[1<>MkBodyCLUSTLOG].free[b&MkBodyCLUSTMASK]);

    return MkBodies[b>>MkBodyCLUSTLOG].mass[b&MkBodyCLUSTMASK];
  }
#else
# define MkBodyGETMASS(b,m) \
  (0.0f + MkBodies[(b) >> MkBodyCLUSTLOG].mass[(b) & MkBodyCLUSTMASK])
#endif

extern MeFloat          MkBodyGetMass(const MkBodyID b);

#include "MkBody.h"

MkBodyClust             *MkBodies;
static unsigned         MkBodiesMax = 0;

void MkBodyInit(const unsigned bodies)
{
  MkBodies = (MkBodyClust *) MemoryCreate(bodies>>MkBodyCLUSTLOG
                                          * sizeof (struct MkBodyClust));

  if (MkBodies == 0)
    return;

  MkBodiesMax = bodies;

  {
    register unsigned i;

    for (i = 0; i < MkBodiesMax; i++)
      MkBodies[i>>MkBodyCLUSTLOG].free[i&MkBodyCLUSTMASK] = 1;
  }
}

MkBodyID MkBodyCreate()
{
  register unsigned i;

  for (i = 0; i < MkBodiesMax; i++)
  {
    register char *const f
      = &MkBodies[i>>MkBodyCLUSTLOG].free[i&MkBodyCLUSTMASK];

    if (*f != 0)
    { 
      *f = 0;
      return i;
    }
  }

  return (MkBodyID) -1;
}

MeFloat MkBodyGetMass(const MkBodyID b)
{
  assert (b < MkBodiesMax
          && !MkBodies[b>>MkBodyCLUSTLOG].free[b&MkBodyCLUSTMASK]);
  return MkBodies[b>>MkBodyCLUSTLOG].mass[b&MkBodyCLUSTMASK];
}

MeFloat MkBodyGetMass(MkBodyID b)
{
  assert (b < MkBodiesMax
          && !MkBodies[b>>MkBodyCLUSTLOG].free[b&MkBodyCLUSTMASK]);
  return MkBodies[b>>MkBodyCLUSTLOG].mass[b&MkBodyCLUSTMASK];
}

void MkBodyDestroy(MkBodyID b)
{
  assert (b < MkBodiesMax
          && !MkBodies[b>>MkBodyCLUSTLOG].free[b&MkBodyCLUSTMASK]);
  MkBodies[b>>MkBodyCLUSTLOG].free[b&MkBodyCLUSTMASK] = 1;
}

void MkBodyExit()
{
  assert (MkBodies != 0 && MkBodiesMax != 0);
  MemoryDestroy(MkBodies);
  MkBodiesMax = 0;
}

class Base
{
  float                 p1;
public:
  float                 m1;
  void                  f1();
};

class DerivedA: Base
{
  int                   p2;
public:
  int                   m2;
  void                  f2();
};

class DerivedB: Base
{
  char                  p3;
public:
  char                  m3;
  void                  f3();
};

typedef struct Base     *BaseID;
float                   BaseGetM1(BaseID b);
float                   BaseSetM1(BaseID b,float v);
void                    BaseF1(BaseID b);

typedef struct Derived1ID Derived1ID;
float                   Derived1GetM1(Derived1ID b);
float                   Derived1SetM1(Derived1ID b,float v);
int                     Derived1GetM2(Derived1ID b);
int                     Derived1SetM2(Derived1ID b,int v);
void                    Derived1F1(Derived1ID b);
void                    Derived1F2(Derived1ID b);

typedef struct Derived2ID Derived2ID;
float                   Derived2GetM1(Derived2ID b);
float                   Derived2SetM1(Derived2ID b,float v);
char                    Derived2GetM3(Derived2ID b);
char                    Derived2SetM3(Derived2ID b,char v);
void                    Derived2F1(Derived2ID b);
void                    Derived2F3(Derived2ID b);

typedef struct Base     *BaseID;
float                   BaseGetM1(BaseID b);
float                   BaseSetM1(BaseID b,float v);
void                    BaseF1(BaseID b);

typedef struct Derived1ID Derived1ID;
BaseID                  Derived1QuaBase(Derived1ID d1);
int                     Derived1GetM2(Derived1ID d1);
int                     Derived1SetM2(Derived1ID d1,int v);
void                    Derived1F2(Derived1ID d1);

typedef struct Derived2ID Derived2ID;
BaseID                  Derived2QuaBase(Derived2ID d2);
char                    Derived2GetM3(Derived2ID d2);
char                    Derived2SetM3(Derived2ID d2,char v);
void                    Derived2F3(Derived2ID d2);

extern "C" BaseID Derived1QuaBase(Derived1ID d1)  { return d1; }
extern "C" BaseID Derived2QuaBase(Derived2ID d2)  { return d2; }

#if (__GNUC__) || (_MSC_VER)
  static __inline BaseID Derived1QuaBase(Derived1ID d1) { return (BaseID) d1; }
  static __inline BaseID Derived2QuaBase(Derived2ID d2) { return (BaseID) d2; }
#else
  /* No type checking unfortunately */
# define Derived1QuaBase(d1) ((BaseID) (d1))
# define Derived2QuaBase(d2) ((BaseID) (d2))
#endif

Appendix: API mail, news and web style

• Mail/news messages, and program comments, should be in simple ASCII text.
• Each mail/news paragraph should be filled to no more than 80 columns.
• USENET emphasis conventions (_xxx_ for italics, *xxx* for bold, for example) for ASCII text are recommended. Also "xxx" for quoting text as strings, 'xxx' for referring to the programmatic entity called "xxx", and $x$ for the mathematical entity called "x". I also use `` and '' to indicate quoting in the natural language sense, not the computer sense.
• Documents should be in HTML or simple ASCII text rather than MS Word. If MS Word is indispensable (and it almost never is) then they should be in RTF rather than in native MS Word binary format.
• HTML pages must have program text between "<code>" and "</code>".

I *strongly* suggest that the _identifier_ that names a variable be
indicated as "ident", while the variable itself be indicated as
'ident'. However it is true that normally ``everything goes''.

One can then say that the the value of 'ident' should be $sqrt(log(n))$, 
while one can also say that the variable called "ident" probably is a
_local_ variable given the rule ``local names begin with a lowercase
letter like "a"''

Version history

These are notes on the most significant differences between different versions and revisions of this document.

Version 4, 2001/04/13

Added the notion of revealing object handle implementation types as discussed on the API mailing list long ago.
• Removed the demented demand that all object handles be implemented as pointers even if they are not pointers.
• Changed delete to destroy in the example code for consistency.

Version 3, 2000/06/02

• Revised according to Manny's suggestions.
• Put the section on formatting text for email, news and comments to the end as an appendix.
• Added explanation of what is a Qua function.

Version 3, 2000/05/17

• Added pointers to the Doxygen documentation and to the guide on how to write JavaDoc style comments.
• Some cosmetic/typo fixes.

Version 3, 2000/02/23

• Object handles are opaque IDs, which are usually pointers, and sometimes integers. Object attributes are accessed via accessor/mutator functions or macros.
• In explicitly authorised cases like KEA 1, the memory layout of an object can be documented, but accessor/mutator functions or macros/inlines must still be provided, and their use encouraged.

Version 3, 2000/02/15

• Standard operations names have now been defined.
• A note added to make sure that header file names have the same style as identifiers.
• The Issues sections has been moved to before rather than after the Examples sections.
• The names of prefixes for dynamics and collision have now been defined.
• Added as issues the prefixes for cloth and particles.
• Added recommendation for Doxygen with JavaDoc style comments.

Version 2, 2000/01/27

• Object handles are pointers, and the memory layout of objects as a rule should not be documented, and only accessor/mutator functions or macros should be used.
• In explicitly authorised cases like KEA 1, the memory layout of an object can be documented, but accessor/mutator functions or macros/inlines must still be provided, and their use encouraged.
• More advice on defining macro bodies.
• Added naming of common operations as an issue.

Version 2, 2000/01/21

• Object handles are pointers, and the memory layout of objects can be documented and used, and/or accessor/mutator functions or macros can be used.
• Member function names should be like PkgTypeOpField.

Version 1

• Object handles are opaque, and the memory layout of objects must be too, and all object properties must have accessor/mutator functions or macros.
• Member function names should look like PkgTypeFieldOp.