Naming Rules in Code: Bad vs. Clean Comparison

This article is proudly presented by Foreign IT Review (www.aqee.net)

Beginners always spend a lot of time learning programming languages, syntax, techniques, and the use of programming tools. They believe that if they master these technical skills, they can become decent programmers. However, the purpose of computer programming is not about mastering these technologies and tools—it is about creating corresponding solutions for specific problems in specific domains, which programmers achieve through collaboration with one another. So, it is very important that you can precisely express your ideas through code so that others can understand your intent by reading your code.

Let us first look at a quote from programming master Robert C. Martin’s masterpiece Clean Code:

“The purpose of comments is to compensate for the inadequacy of the code itself in expressing intent.”

This can be simply understood as: if your code needs comments, most likely your code is poorly written. Similarly, if you cannot fully express your thoughts on a problem or algorithm through code without comments, that is a sign of failure. Ultimately, this means you need comments to clarify a portion of your thinking that is not evident in the code. Good code allows anyone to understand it without needing any comments. A good coding style embeds all the information necessary to understand the problem within the code itself.

In programming theory, there is a concept called “self-documenting source code.” For a piece of code, a common self-documenting mechanism is following some loosely defined naming conventions for variables, methods, and objects. The main purpose of this is to make the source code easier to read and understand. As a result, it is also easier to maintain and extend.

In this article, I will give some examples to illustrate what “bad code” and “clean code” look like.

Names Should Reveal Intent

How to name things has always been a perennial problem in programming. Some programmers like to simplify, shorten, or encrypt names so that only they themselves can understand them. Let us look at some examples:

Bad Code:

“d” can represent anything. The author uses comments to express his intent, but does not choose to express it through code. And “faid” can easily be misinterpreted as an ID.

Clean Code:

Avoid Misleading Information When Naming

Misleading information is worse than no information at all. Some programmers like to “hide” important information, and sometimes they write code that can be misleading.

Bad Code:

The variable “customerList” is not actually a list. It is an ordinary array (or a collection of customers). Additionally, “theTable” is an object of type Table (you can easily discover its type using an IDE), and the word “the” is unnecessary noise.

Clean Code:

Names Should Have Appropriate Length

In high-level programming languages, the length of variable names is typically not very restricted. Variable names can be almost any length. Nevertheless, this can also make code frustrating.

Bad Code:

A good name should contain only the necessary words to express a concept. Any unnecessary words will make the name longer and harder to understand. Shorter names are better, provided they express the complete meaning within the context (in the context of placing an order, “customersInOrder” is better than “list”).

Clean Code:

Keep Coding Conventions Consistent When Naming, Let Conventions Help Understand the Code

Every programming technology (language) has its own “style,” known as coding conventions. Programmers should follow these conventions when writing code, because other programmers also know them and write in this style. Let us look at a bad code example without clear conventions. The following code does not follow well-known “coding conventions” (such as PascalCase, camelCase, Hungarian notation). Worse, there is a meaningless bool variable “change.” This is a verb (used to describe an action), but the bool value here describes a state, so an adjective would be more appropriate.

Bad Code:

Looking at just a portion of the code, you should immediately understand what type something is, simply by looking at its naming approach.

For example: when you see “_name”, you know it is a private variable. You should use this convention everywhere, with no exceptions.

Clean Code:

Use the Same Word for the Same Concept When Naming

Defining concepts is hard. During software development, a lot of time is spent analyzing business scenarios and thinking about the correct definitions for all elements. These concepts are always a headache for programmers.

Bad Code:

First:

The author of the code tries to express the concept of “get the data,” but uses multiple words: “load,” “fetch,” “get.” A single concept should be expressed using only one word (within the same context).

Second:

“set” is used for two different concepts: first, “data loading to view,” and second, “setting a value of an object.” These are two different concepts, and you should use different words for them.

Clean Code:

Use Business Domain-Relevant Words When Naming

All code written by programmers is connected to the logic of business domain scenarios. To help everyone involved understand better, the program should use names that are meaningful in the domain context.

Bad Code:

When writing code for a specific domain, you should always consider using names that are relevant to that domain. In the future, when another person (not necessarily a programmer, perhaps a tester) looks at your code, they will be able to easily understand what your code means within that business domain (without needing business logic knowledge). What you should consider first is the business problem, and only then how to solve it.

Clean Code:

Use Words That Are Meaningful in the Specific Context When Naming

Names in code all have their own context. Context is very important for understanding a name, because it provides additional information. Let us look at a typical “address” context:

Bad Code:

In most cases, “Post Code” is usually part of an address, and obviously, a postal code cannot be used on its own (unless you are developing an application specifically for handling postal codes). So, there is no need to prefix “PostCode” with “address.” More importantly, all of this information has a contextual container: a namespace, a class.

In object-oriented programming, an “Address” class should be used to express this address information.

Clean Code:

Summary of Naming Conventions

To summarize, as a programmer, you should:

• Name things to express concepts
• Pay attention to name length—names should contain only the necessary words
• Coding conventions help understand code, and you should use them
• Do not mix up names
• Names should be meaningful in the business domain and in context