Clean Code: Meaningful Names

Every program should use meaningful names, not only for instant programming efficiency but also for long-term maintainability. In Chapter 2 of Clean Code, Tim Ottinger describes how to write meaningful names to improve your code quality.


Principle 1: Names with Purpose

As we define a variable, either a global one or an intermediate one, it has a specific usage. Therefore, we should use names showing their purpose instead of some annoying meaningless names like a.

For example, if we define a variable called d in the context of dates and time:

int d;

A reader may have different interpretations of d, like the elapsed time in days, days since creation, days since modification, and etc. For a reader unfamiliar with the code, including the ones reading it after three weeks from writing it, one would definitely need to read more passages of codes and rely on the comments to guess the exact meaning of d. Moreover, the best comment is without comment (I will discuss it in the comment section). So why don’t we using meaningful names at the very beginning?

int elapsedTimeInDays;
int daysSinceCreation;
int daysSinceModification;
int fileAgeInDays;

Furthermore, meaningful naming in a loop is also essential. Compare the following two examples in Go:

func f1(list []int) int {
    s := 0
    for (i := 1; i<len(list); i++) {
        s += list[i]
    }
    return s
}
func sumWithoutFirstElement(listToSum []int) int {
    sum := 0
    for (index := 1; index < len(listToSum); index ++){
        sum += listToSum[index]
    }
    return sum
}

Obviously, both codes do the same job, but which one would you prefer? Personally speaking, I would prefer the second one. Firstly, its function name clearly states its purpose. No one knows the meaning of f1, but everyone should know the meaning of sum without (the) first element. Moreover, it uses the name listToSum, sum, and index as variable names.

Will Longer Names Affect Coding Speed?

My answer is no, as long as your editor supports code hint. If you are using IDEs like Visual Studio, Visual Studio Code, and JetBrains’ stuff, your editor will automatically show you all the same prefix names. If you have a consistent naming convention, like the verb-noun-preposition-noun styles, you only need to type as if you are writing English essays, and the editor will show you the correct name.

More importantly, enhancing with the code hint, your coding speed is mostly affected by revoking the correct name but not typing it. Comparatively, using a meaningless name like f1 requires you much more effort to remember a mapping from f1 to its real usage and makes you tiring. Instant memory is critical and precious for programming, so if you need to navigate a large project, save your memory from naming!

Principle 2: Use Pronounceable Names

Using pronounceable names is essential especially when working in a team or asking for help. Consider the following example: what is the meaning of genymdhms? Actually, it represents the generation-date, year, month, day, hour, minute, and second. If you have a name genymdhms, how would you pronounce it?? However, consider the name generationTimeStamp, isn’t it much better?

Since writing codes is not writing Incantations but is expressing logic and ideas, please do not use those incantation names!

Principle 3: Build a Consistent Dictionary of Terminologies

Computer Science and other subjects have various terminologies. For example, vertex and node are essentially the same things, but what if you have one function called addVertex() and another one called getNodes()? I believe that every reader will be stuck at the first glance, and one would need a careful read of your codes to confirm if vertex and node have the same meaning in your context.

There are countless examples we have seen. It is confusing to have a controller and a manager and a driver in the same context. To get rid of it, one should write a consistent dictionary of terminologies before start coding and update it in the whole procedure.

Moreover, usually there are solution domain names and problem domain names specific to your codes context. In this case, an explanation in your dictionary as well as some comment in the declaration of variables are important to improve the understanding of your codes.


Read more about the Clean Code series:

To buy the book:

3 thoughts on “Clean Code: Meaningful Names

Leave a Reply

Your email address will not be published.