6. Structures and Unions

In this section, when `structure' is written in a rule, consider the rule to apply equally to unions.

tags

Each structure should be defined and used in terms of its tag; e.g., struct node. The tag of a structure declared within a public header file should include the module's name prefix.

An exception might be a structure defined and used within the scope of a function (e.g., for use as a lookup table) if such a structure does not need a name at all, but more often even such a structure needs a tag.

names

Do not include struct or record or similar in a structure's tag. Do put a module's name prefix at the beginning of a member's name if the structure is declared within a public header file.

In a union that directly contains many structures as members, give these members the same names as their structure tags. If the structures' names have a common prefix or suffix (other than the module name prefix), omit it.

comments

Precede a structure definition by a comment that describes its intended usage.

Within a structure definition, every member should have a comment to explain its purpose. These comments should be to the right of the member declaration on the same line. All the member comments for a structure should ideally be aligned flush to a single tab position, but this is not always possible. For a single too-long declaration or, within a large structure, a few of them, it's okay to put the comment on the next line (but still aligned with the rest of the comments).

If a structure has more than a few members, then the members should be divided into logical groups, each separated by a blank line. Each group should be headed by an explanatory comment on a line of its own.

If a member or group of members is relevant only if another member of the structure is set to a particular value, or if the program is in a particular mode, etc., indicate that as part of a comment.

(These are the same as the rules that apply to local variables.)

bit fields

For bit fields whose values are enumerated (Boolean values, etc.), not numbers, consider using bit operations on an unsigned type instead.

Do not declare bit fields of type int: ANSI allows these to be either signed or unsigned according to the compiler's whim. Use unsigned int or signed int.

order

Try to order structure members such that they pack well on a system with 2-byte shorts and 4-byte ints and longs. Prefer clear organization to size optimization in the absence of profiling data that shows a clear benefit.

It is acceptable to make use of the ANSI guarantee that a pointer to a structure is a pointer to its first member, and vice versa, but the fact that it is should be clearly marked in a comment just before the first member of the structure.

magic

Consider including a magic number in each structure and testing for it in each function that manipulates the structure. This magic number and tests should be omitted if NDEBUG is defined.

external data

Avoid using structures to represent external data structures such as binary file formats or network packets, because padding between structure members differs among environments and the way to turn it off varies among compilers, if it can be done at all.