Identifier Naming Details

The naming conventions recommended in this section are specific to the C programming language. These conventions take full advantage of the identifier naming facilities offered by the standard definition of C language. Lower and upper case letters as well as '_' are used in this naming convention. All identifiers are expected to be unique with in the first 24 characters.

Concept of a module and hiding in C is limited to the source file. The scope of an identifier outside of a source file is global. Explicit importing and exporting of identifiers is not supported in standard C. This naming convention tries to address this known deficiency in C.

All identifiers are composed of two elements: module prefix and qualifier. Each module is identified by a module prefix. A module prefix is a short name (normally 1 to 4 characters long) followed by an '_'. The case of the module prefix specifies the scope of the identifier with regard to that module. Identifiers exported by a module, have an all upper-case module prefix. An all lower case module prefix signifies that although the identifier is needed by more than one source file within the implementation of the module, it is purely private to the module and need not be exposed to any users of the module. Purely local identifiers need not have the module prefix component and consist of a pure qualifier. In addition to conveying the scope of the identifier, this convention results in prevention of naming collisions across independent modules.

The qualifier component of an identifier mainly conveys the semantic attributes of the identifier. The qualifier component may consist of many words. With the exception of the first word, all following words start with upper-case. The first character of the qualifier conveys some type information. Variables, functions, parameters and structure fields begin with lower-case, the then upper and lower-case mixed. Typedefs, struct/union/enum tags named with upper-case groups. Although not clearly specified in the language definition, typedefs name space is different from struct/union/enum tags name space. Name space overloading is encouraged.

This convention results into clear usage of the same name for a number of related identifiers. This is demonstrated in the following example.

        typedef struct SapSelector {
                Int len;
                Byte addr[NSAPSZ];
        } SapSelector;

        SapSelector sapSelector;

Same descriptive name "sapSelector" is used for the structure tag identifier, the type definition identifier and the variable identifier for a generic instance.

Naming GuideLines

A set of recommendations are proposed for qualifier naming.

Grouping/Classing

A concept is often expressed through a set of related identifiers. Within a module, related identifiers can be grouped in a variety of ways. Grouping with regard to the data class often works fine. Take the case of SAP management in "N_" module, N_sapCreate, N_sapDelete, n_SapInfo, N_SapDesc would be considered natural choices.

Procedures

A verb followed by noun is often a good choice.

Labels

Same as Procedures.

Booleans

A phrase expressing the TRUE case of the variable.

Abbreviations

A number of abbreviations are commonly used to express well defined concepts with in the scope of OSI implementation. These abbreviations are commonly used for identifier naming.

Req

A request primitive.

Rsp

A response primitive.

Ind

An indication primitive.

Cnf

A confirmation primitive.

Sap

Service Access Point.

Cep

Connection End Point.

Du

Data Unit.

Pdu

Protocol Data Unit.

Sdu

Service Data Unit.

Pci

Protocol Control Information.

Buf

Buffer.

Addr

Address.

Sel

Selector.

Src

Source.

Dst

Destination.

Loc

Local. Matches with Rem.

Rem

Remote. Matches with Loc.

Seq

Sequence. Head of a linked list of ordered elements.

Set

(Noun) Head of a linked list of unordered elements.

Elem

Element. An element in a sequence, queue, set.

Next

Matches with prev. A valid value.

Prev

Previous. Matches with next. A valid value.

Last

Matches with first. A valid value.

First

Matches with last. A valid value.

Lim

Limit. Not a valid value.

Min

Minimum. A valid value. Compile or link time constant.

Max

Maximum. Not a valid value. Compile or link time constant.

Info

Information. Often used to provide an internal representation of a resource.

Desc

Descriptor. Often used to provide a public handle to a resource.

Ref

Reference. Often used as a prefix to provide a handle to a resource.

Prov

Provider. To identify roles in a service provider/user situation.

User

To identify roles in a service provider/user situation.

Cur

Current.

Val

Value.

Init

Initialize.

Term

Terminate.

Get

Retrieve an information object from an information base.

Set

(Verb) Set an information object in an information base.

Rationale

The primary intentions of the identifier naming convention mentioned above is to convey important information about identifiers while keeping the names short and natural.

The following is a partial list of the intentions of this naming convention.

• Maximize conveying important identifier attributes while keeping the names short and natural.
• Emphasis on semantic information. An identifier's primary responsibility is to convey the natural aspect of what it represents.
• Emphasize module definition and highlight scope recognition. Definition of C language is limited in its ability with regard to modularity and hiding to one source files. This naming convention extends the module and scope concepts beyond one source module.
• It is recognized that complete type information about all identifiers is accessible through their definition and context. Proper tools may be used to perform syntax type checking improve reliability. Some information regarding the type of the identifier is conveyed in this naming convention. The conventions with regard to type allow for name space over loading and minimize name selection.