What's in a name?


It is not true that names will never hurt you. Writing source code is all about clear communication. Good names convey information about the structure of the code. They are an essential tool to aid comprehensibility and maintainability. It is crucial to name things well. Name things well the first time, all the time.

You can only reason about 7 pieces of information concurrently (the Miller number). An object's name should describe it clearly.

Keep in mind that bad names may be due to a poor understanding. The key to good naming may be to understand exactly what you are naming.

If you can't come up with a good name, it may be worth considering if the design needs to be changed.

Clear names should also follow the language's idioms.

Favor clarity over brevity when naming. One letter variable names may be used as loop counters.

Do not use silly names. They make the reader doubt the ability of the original author. Do not use variable names like blah, wibble, foo, or bar. They may seem amusing at first but can create confusion later. Foo and bar should never be used in production code.

Hungarian notation is a controversial naming convention (with many subtly different and slightly incompatible dialects) that was popularized by Microsoft's Win32 APIs.

A variable is like something that you could hold in your hand--it should probably have a noun name. A function is more akin to an action and should probably have a name which is a verb.

Meaningful function names avoid the words be, do, and perform. These are traps that add noise and not value. Functions should be named from the viewpoint of the user and hide the implementation details. They should be named from an external viewpoint. Describe the logical operation, not the implementation.

Classes may have less rigid naming heuristics. Some may have noun names and other may be verbs. If the class seems like it should have a combination of a noun name and verb name, then it may be designed badly.

Avoid redundant words in names. Do not put the word class, data, object, or type in the name of a class.

In C and C++, macros should always be capitalized and nothing else should ever be capitalized.

File naming


Filenames are also important (some languages have restrictions on these, and others have none at all). The code should be split into the maximum number of files that you can. This will make them easier to name and reduce coupling.

The easiest way to avoid problems with how different operating systems treat capitalization differently in filenames is to mandate that all filenames be lowercase. Never exploit the fact that your filesystem considers foo.h and Foo.h to be different.

Bad file naming will make finding particular bits of code a nightmare.

The main principles when it comes to naming:
  • be consistent
  • exploit context
  • use names to your advantage.

Being consistent may be the most important naming principle.

Exploiting context means deleting the superfluous bits that duplicate contextual information. The name will only ever be read in the context it's in. Put things in the smallest scope that you can. A name need not restate the type (this is why Hungarian Notation is an often derided convention).

Do not name cryptically. Avoid terse names but also do not be overly verbose. Make your names accurate. Do not misspell words as this can open a minefield of confusion. Do not name things in a way that is ambiguous or vague. Sexy little abbreviations like i18n should be avoided.

Summary

 
Good programmers know the importance of names. They think about naming and choose appropriate names. They consider all of the forces that must be balanced: length, clarity, context, etc. They see the bigger picture so that the names hold together across the project.

Bad programmers care little about clarity. They produce write-once code that is quick to write and poorly thought out. They ignore idioms, are inconsistent in naming, and do not think holistically about how their piece of code fits into the whole.

Article notes

Is it true that names will never hurt you?
Without uncertainty, what is Miller's number?
What are two groups of six words that should be avoided in naming, three of them specifically because they are redundant?
What are two groups of six words that should be avoided in naming, three of them specifically because they add noise and do not add value?
What is the most important naming principle according to Code Craft?
What does Code Craft say about splitting the code into files?
What kind of word should the name of a function be?
What kind of word should the name of a variable be?
What was one of the things that made Hungarian notation popular?
What might you need to do if you cannot come up with a good name for something in code?
What does Code Craft call i18n?
What is a common cause of bad names, as pointed out by Code Craft?
When should you name things well in programming?
Previous Next