Micriµm, Inc.
Acronyms, Abbreviation and Mnemonics Dictionary
1.00 Introduction
When creating names for variables and functions (identifiers), it is often the practice to use
acronyms (e.g. OS, ISR, TCB and so on), abbreviations (buf, doc etc.) and mnemonics (clr,
cmp, etc.). The use of acronyms, abbreviations and mnemonics (from now on AAM) allows an
identifier to be descriptive while requiring fewer characters. Unfortunately, if AAMs are not used
consistently, they may add confusion. To ensure consistency, we have created a list of AAMs
that we use in all our projects. The same AAM is used throughout, once it is assigned. I call this
list the Acronym, Abbreviation and Mnemonic Dictionary and the list for Micriµm is shown in
Table 1. As we need more AAMs, we will revise this document.
There might be instances where our doesn't make sense for your products/projects. For
instance, if you are an engineering firm working on a project for different clients and the products
that you develop are totally unrelated, then a different list for each project would be more
appropriate; the vocabulary for the farming industry is not the same as the vocabulary for the
defense industry. We use the rule that if all products are similar, they use the same dictionary.
A common dictionary to a project team will also increase the team's productivity. It is important
that consistency be maintained throughout a project, irrespective of the individual programmer(s).
Once buf has been agreed to mean buffer it should be used by all project members instead of
having some individuals use buffer and others use bfr. To further this concept, you should
always use buf even if your identifier can accommodate the full name; stick to buf even if you
can fully write the word buffer.
2
Micriµm, Inc.
Acronyms, Abbreviation and Mnemonics Dictionary
2.00 Creating Identifiers using AAMs
#define constants, macros, variables and function names (i.e. identifiers) should make use of the
file name as a prefix. This prefix makes it easy to locate identifier declarations in medium to large
projects. It also makes it very easy to know where these identifiers are declared and ‘belong’ to.
For example, all functions in a file named KBD.C and functions in a file named VIDEO.C could be
declared as follows:
KBD.C
KbdGetChar()
KbdGetLine()
KbdGetFnctKey()
VIDEO.C
VideoGetAttrib()
VideoPutChar()
VideoPutStr()
VideoSetAttrib()
It's not necessary to use the whole file/module name as a prefix. For example, a file called
KEYBOARD.C could have functions starting with Kbd instead of Keyboard. It is also preferable
to use upper case characters to separate words in an identifier (a.k.a. Camel Back) instead of
using underscores. Underscores don't add any meaning to names and they use up character
spaces.
As much as possible, use 'module-object-operation' format with AAMs. When creating identifiers,
specify the name of the module (or sub-system) first, followed by the object and then the
operation as shown below.
OSSemPost()
OSSemPend()
Here, the module name is OS (Operating System), the object is Sem (Semaphore) and
the operation that can be performed on the object is Post or Pend.
What’s nice about this technique is that it allows you to group similar items together. Of course, it
may be a bit difficult to get used to it in the beginning because it’s more natural to think in terms
of Action-Object such as OSPostSem(). We prefer the Object-Action method because it groups
similar objects with their actions. For example:
OSSemAccept()
OSSemCreate()
OSSemDel()
OSSemPost()
OSSemPend()
OSSemQuery()
3
Micriµm, Inc.
Acronyms, Abbreviation and Mnemonics Dictionary
We have recently started to append an underscore character after the module name to separate
the module from the Object-Action. Using the above function name as examples, the function
names would now look as follows:
OS_SemAccept()
OS_SemCreate()
OS_SemDel()
OS_SemPost()
OS_SemPend()
OS_SemQuery()
4
