C/C++ Naming conventions (Part I)

Update [2/19/2008]

The Use Case article on Wikipedia provides more support for verb-object form.

Update [2/19/2009]

Added some links for literate programming.

Naming conventions are an important and very practical aspect of literate programming. There are two fundamental requirements for naming conventions:

Consistency of form, the “what it is” factor: Do the names variables, members, functions, methods and other accoutrements of the source code have the same appearance when performing similar functions?
Consistency of meaning, the “what it does” factor: Do the names of various elements of source code indicate their purpose?

Consistency of form

Does the naming scheme use the same form for like purposes? Consider the form differences between the following name for an accessor method for setting rotation:

rotateSet
rotationSet
set_rotation
set_rotate
RotateSet
SetRotation
setRotation
etc.

Think carefully about the purpose of the method, and how you might explain the purpose of the method to your mother: “Ok Mom, this method here sets the amount of rotation that the foobar can spin.” Reexamine our candidate names above. I could say something like obviously, there are only two possible names for this function and leave it at that.

But I won’t.

What I will say is this: you won’t find me using anything other than either set_rotation , SetRotation or possibly setRotation in any code that I write. And of these three, I will only use set_rotation given I have the choice of preference.

Why is this?

verb_object (set_rotation) form over verb_verb form (set_rotate).
Natural word order: I am a native English speaker, I use subject-verb-object grammar. Considering a function call as an imperative statement (“Go there” “Do that”), verb_object is like natural language.
Lower case using underscore separation communicates the purpose without appearing overly bombastic. Using CamelCase for get/set destroys it’s usefulness in more important contexts.

Consistency of meaning

Scope: Does the function name indicate in what part of the program the function is applied?
Purpose: Does the function name allow the caller an educated guess as to the purpose of the function?

Consider scope. Does the function or method name provide any clues at all? In C++, the class name helps. In straight, vanilla C code, one very convenient way to handle “class” names is by prefixing the “class” name. Let’s define a “box” class and examine a couple of options for a typical accessor method:

set_boxwidth: This is pretty good, uses verb_object convention.
box_set_width: This is better, puts the class name in the same position as it would be in C++, emphasizes our interest is really in working with boxes, not setting member variables.