Example identifier prefix convention

The following excerpt from the GNU libavl manual illustrates a sample convention for prefixing identifier names in a library.

2.2 Identifiers
===============

   In C programming it is necessary to be careful if we expect to avoid
clashes between our own names and those used by others.  Any identifiers
that we pick might also be used by others.  The usual solution is to
adopt a prefix that is applied to the beginning of every identifier that
can be visible in code outside a single source file.  In particular,
most identifiers in a library's public header files must be prefixed.

   `libavl' is a collection of mostly independent modules, each of which
implements the table ADT.  Each module has its own, different identifier
prefix.  Identifiers that begin with this prefix are reserved for any
use in source files that #include the module header file.  Also
reserved (for use as macro names) are identifiers that begin with the
all-uppercase version of the prefix.  Both sets of identifiers are also
reserved as external names(1) throughout any program that uses the
module.

   In addition, all identifiers that begin with libavl_ or LIBAVL_ are
reserved for any use in source files that #include any `libavl' module.
Likewise, these identifiers are reserved as external names in any
program that uses any `libavl' module.  This is primarily to allow for
future expansion, but see *Note Memory Allocation:: and Exercise 2.5-1
for a sample use.

   The prefix used in code samples in this chapter is tbl_, short for
"table".  This can be considered a generic substitute for the prefix
used by any of the table implementation.  All of the statements about
these functions here apply equally to all of the table implementation in
later chapters, except that the tbl_ prefix must be replaced by the
prefix used by the chapter's table implementation.

Exercises:

1. The following kinds of identifiers are among those that might appear
in a header file.  Which of them can be safely appear unprefixed?  Why?

  a. Parameter names within function prototypes.

  b. Macro parameter names.

  c. Structure and union tags.

  d. Structure and union member names.

2. Suppose that we create a module for reporting errors.  Why is err_ a
poorly chosen prefix for the module's identifiers?

   ---------- Footnotes ----------

   (1) External names are identifiers visible outside a single source
file.  These are, mainly, non-static functions and variables declared
outside a function.

Section 2.2
-----------

1.  Only macro parameter names can safely appear prefixless.  Macro
parameter names are significant only in a scope from their declaration
to the end of the macro definition.  Macro parameters may even be named
as otherwise reserved C keywords such as int and while, although this
is a bad idea.

   The main reason that the other kinds of identifiers must be prefixed
is the possibility of a macro having the same name.  A surprise macro
expansion in the midst of a function prototype can lead to puzzling
compiler diagnostics.

2.  The capitalized equivalent is ERR_, which is a reserved identifier.
All identifiers that begin with an uppercase `E' followed by a digit or
capital letter are reserved in many contexts.  It is best to avoid them
entirely.  There are other identifiers to avoid, too.  The article
cited below has a handy list.

See also:  [Brown 2001].

Appendix A References
*********************

[Brown 2001].   Brown, S., "Identifiers NOT To Use in C Programs".  Oak
Road Systems, Feb. 15, 2001.
`http://www.oakroadsystems.com/tech/c-predef.htm'.

Last updated 02 Jan 2004 23:43. Copyright © 2004 Ben Pfaff.
May be freely redistributed, but copyright notice must be retained.