C.8. Structures and Unions

C.8.1. Declaration

All application datatypes and private datatypes defined in library source files should be declared static. Public datatypes declared in library header files should not include this keyword!

Always use the EMBOSS method of declaring structures and unions, i.e. using #define and typedef in the manner shown:

typedef struct AjSStr 
{
    ajuint  Res;
    ajuint  Len;
    char   *Ptr;
    ajuint  Use;
    ajint   Padding;
}   AjOStr;
#define AjPStr AjOStr*
typedef AjPStr* AjPPStr;

The declaration must contain a structure name (AjSStr), object name (AjOStr) and pointer name (AjPStr) even if these are not used. In the example above, a pointer to the object pointer is also defined (AjPPStr). This is optional and should only be included if needed.

C.8.2. Naming Conventions

The naming convention for AJAX public (external) structures is:

Structure name

AjSName

Object name

AjOName

Pointer name

AjPName

The naming convention for NUCLEUS public (external) structures is:

Structure name

EmbSName

Object name

EmbOName

Pointer name

EmbPName

Use of this convention, i.e. the P prefix for pointers, avoids problems where a pointer could appear to be an object in its own right.

This, for example, is bad practice in naming:

typedef struct T *T;
...
T t;

It is not clear from the variable name that t is a pointer.

The naming convention for private structures drops the Aj and Emb prefix. For private structures whether in AJAX, NUCLEUS or application code use:

Structure name

SName

Object name

OName

Pointer name

PName

For example:

/* @datastatic PBlastType *****************************************************
**
** DbiBlast types
**
** @attr ExtT [const char*] Table filename extension
** @attr ExtH [const char*] Header filename extension
** @attr ExtS [const char*] Sequence filename extension
** @attr IsProtein [AjBool] true for protein
** @attr IsBlast2 [AjBool] blast2.x or blast 1.x
** @attr Type [ajint] enumerated type
** @attr Padding [char[4]] Padding to alignment boundary
******************************************************************************/

typedef struct SBlastType
{
   const char* ExtT;
   const char* ExtH;
   const char* ExtS;
   AjBool      IsProtein;
   AjBool      IsBlast2;
   ajint       Type;
   char        Padding[4];
}  OBlastType;

#define PBlastType OBlastType*

C.8.3. Datatype Documentation

All public objects must be documented in a standard way (Appendix D, Code Documentation Standards). Separate individual objects by suitable whitespace (4 newlines).