Naming

Choosing Names

1. Names correspond to the purpose of the construct they are applied to.
2. If possible, names are never abbreviated. If they are too long (compiler refuses the name or cannot tell apart), meaningful and mnemonic abbreviations may be used.
   Counter-example: is 'tmt' used for transmit or timeout?.
   Exception: ‘historically grown’ standard terms ('rcv', 'snd', etc.)
3. Underscores are forbidden within names. They are used to seperate module prefixes from identifiers.

Forbidden:	Read_Master_Data()
Allowed:	ReadMasterData(); Accnt_ReadMasterData();

4. Names are chosen principally from the programmers native language. Exceptions are technical terms.

Multi-lingual names (GetStapelEintrag) are strictly forbidden.

Names or parts of names that have the significance of key words are chosen in english. These exceptions are explicitly pointed out. There are no other exceptions.

5. If there arise translation problems, common terms are to be collected (in a glossary) and to be defined as a guideline (translated, if neccessary). Those translations are based on technical dictionaries or other documents from professional technical translators.
6. Abbreviations from external systems or libraries may be used. There is no need to redefine terms like MFC or OWL.

Types

1. Names defined with typedef are written in uppercase and may contain underscores. (except structs, classes and pointers to structs or classes).

typedef int ALERT_PRIORITY;

2. Names of enumeration types are formed like typedefs. The names of public enumeration types have a module prefix. Their denoter's names begin with a descriptive prefix derived from the enumeration type's name. Since the denoters have the significance of public constants, their names are written in uppercase letters.

typedef enum { F_RED, F_GREEN, F_BLUE } COLOR;
typedef enum { AC_READONLY, AC_WRITEONLY, AC_RANDOM } MEM_ACCESS;

3. Names of structs and classes start with an uppercase C and indentify classifictions of nouns. They must not contain underscores. Multiple words are distiguished by using uppercase letters.

typdef struct CComplex // though typedef, mixed case for structs!
{
    float m_fReal;
    float m_fImag;
} CComplex;

class CDatabase;
class CFastMemory;

typedef CComplex* PComplex;
typedef CFastMemory* PFastMemory;

Data Objects

1. Variable names always start with a lowercase letter (the module prefix is not part of the name).
2. Variable names identify nouns. If neccessary, an article and/or adjectives may preceed the noun. (e.g. to fulfill the preceeding demand).

int nUpperLimit;
CDocument theDocument;
void* pDataBuffer;

3. Names of private variables start with an underscore.

int _nTotalNumerOfErrors = 0;

4. If a public variable is inevitable, its name gets a module prefix.

int* Mmgr_pTheOnlyMemoryPool;

5. Names of constants created with #define or public declared constants are written in upercase letters and may contain underscores. Names of public constants may also follow this convention.

#define UPPER_LIMIT 1234
const int UPPER_LIMIT = 1234;
const int nUpperLimit = 1234;
const int Stack_nUpperLimit = 1234;

6. Variables must not be used for different purposes within their scopes.
7. Variable names start with a type prefix. The actual name starts with an uppercase letter followed by lowercase letters. Multiple words are distiguished by using uppercase letters. Underscores must not be used. Exception: loop variables (i, j, …)

int nFehler;
int nGesuchterWert;
LPCSTR lpszBenutzerName;

8. Names of data elements get the prefix m_.

class CErrorState
{
    int m_nStateCode;
    LPCSTR m_lpszErrorMessage
};

Macroes, Functions

1. (C) Names of Macroes are written in uppercase letters and may contain underscores.

#define ABS(x) (0 > (x) ? -(x) : (x))

(C++) Using macroes is inadmissable. Use inline- or template functions instead.

2. Names of functions start with an uppercase letter, followed by lowercase letters. Uppercase letters are used within compund names. Underscores are not allowed. Names of public functions get a module prefix.

void SearchTree(const PNode pExpressionTree);
BOOL Msg_MessageIsPresent(void);

3. Names of functions without a return value or that return a state value start with a verb. Prefer the imperative to the infinitive (wouldn't be a doubt in english, but other languages like German will seduce the programmer to fail).

not	TagesdatumSetzen(const PGmsDatum pDatum),
but	SetzeTagesdatum(const PGmsDatum pDatum); void SendePaket(const PGmsPaket pPaket); ERRORTYPE PruefeName(LPCSTR pName);

1. Names of functions with a return value start with a noun or with an adjective that describes the returned value.

ALERT NextAlert(const PTIME pStartingTime);
LPCSTR UserName(const int nUserId);

and not:

LPCSTR ReadUserName(int nUserId)!

2. Names of functions with a boolean return value start with Is or Has:

bool IsValidName(LPCSTR pName);
bool HasChildren(void);

3. Names of conversion functions are formed as „Source"To„Destination".

int HexToBinary(LPCSTR lpszHexNumber);

4. (C, Pascal) An initialization funktion is a function that creates a data structure from the structure's components. Initialization functions are different from conversion functions, because they yield a data structure. Names of initialization functions start with Build. the name starts with New, if a pointer to the new object is returned. The latter return a pointer to the allocated memory, which is to be deallocated by the function's caller by using a deallocation function. Names of deallocation functions start with Delete. These name prefixes have the significance of key words (they correspond to the C++ operators new and delete) and are therefore always written in english.

void BuildTime /* (C) */
    (
        PTime this,
        const int nHours,
        const int nMinutes,
        const int nSeconds
    );

PTime NewTime
    (
        const int nHours,
        const int nMinutes,
        const int nSeconds
    );

void DeleteTime(PTime pTime);

(C++, Delphi) Initialization functions are inadmissable. Use constructors, cast operators and destructors instead (C++: in context with new and delete operators). Namen of functions that allocate heap memory for the returned object, which must be deallocated by the caller, start with New.

Type Prefixes

Essential parts of the succeeding tables have been suggested by Microsoft for Windows applications [Petz90].

Type Prefixes For Variable Names

1. Instances of userdefined structs or classes may, but are not forced to get a specific prefix.
2. Variables representing an enum type, get the prefix n, since their sizes usually depend on the (system dependent) size of an integer.
3. Prefixes as for modules may be useful for user defined classes or structs. This prefix is mentioned in the class header.

struct CConfigurationData;
CConfigurationData cnfDevice1;

4. Other system or compiler dependent features that are not mentioned here (like pointers to special memory areas) are to be listed in project specific guidelines.

General Name Prefixes

The sample prefix Mod replaces a useful abbreviation of the module name (preferribly 3-5 characters).

Symbols Used By Windows-Applications

[continue with "Programming Style Guide"] | [TOC] | [Introduction] | [Layout] | [Programming Style Guide] | [Annexes]

Copyright © 1997-98 by Uwe Sauerland