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:

  1. 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?
  2. 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 its usefulness in more important contexts, for example, class definitions or typedefs.

Word order matters in natural languages, it matter in computer languages, and it should matter in variable, function and method naming as well.

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:

  1. set_boxwidth: This is pretty good, uses verb_object convention. The subject, however, is implied: who, exactly, is setting the box width?
  2. 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. More importantly, this form moves the subject from an unknown actor to box. In other words, we direct box to set its own width. In natural language this might read "Box, set your width."

C++ handles the latter by having set_width as a member method of some Box class. In C, box_ prefix can imply a file-scoped struct functioning as a class.

Read more on literate programming

It’s been written that the primary purpose of a computer language is to communicate with other programmers. While patently untrue (programs are written to execute in response to business requirements), adopting a literate programming mindset makes one’s own code much easier to read and maintain. And while it can be a bit of work, it’s also a lot of fun.

Here’s more about literate programming:

Have fun out there!