Beginner programmers always spend a lot of time on learning a programming language, code syntax, technology and tools. They think, if they master the craft of technologies, they will become good programmers. However, object programming is not about mastering the tools, it is about creating a solution to a problem in a particular domain and to do it in cooperation with other programmers. Therefore, it is very important to express your thoughts in code precisely and in a result to be understood by other people.
Let’s start with a great quote by the Clean Code guru, Robert C. Martin:
“The proper use of comments is to compensate for our failure to express our self in code”
[„Clean Code: A Handbook of Agile Software Craftsmanship” Robert C. Martin]
This phrase simply means that if there is a need to comment your code, it is most probable that your code is bad. Also, it might indicate a failure when you cannot express all your thoughts about a problem or an algorithm within code without comments. And finally, that means you expressed a part of a concept in comment not in the commented code. Good code should be understandable to everyone without reading any comments. Good coding style is about storing all necessary information to understand the problem in code.
In programming theory, there is a concept of “self-describing source code”. It is a common descriptor for source code that follows certain loosely defined conventions for naming and structure. The main objective for self-describing is to make source code easier to read and understand. Therefore, it is easier to maintain or extend existing code.
Within the scope of this article I would like to present some examples of “bad code” compared with “clean code”.
Names have to reveal your intentions
Thinking about names is always a problem when writing code. Some programmers are trying to simplify, shorten or encode names in they-only-know way. Let’s have a look at a few examples:
// elapsed time in days
Name “d” could mean anything. The author used comment to reveal his intentions, instead of including it in code. Name “faid” could be mistaken for identity (ID).
No information at all is better than misleading information. Sometimes programmers try to “hide” some important information, however they tend also to create confusing parts of code sometimes.
Variable “customerList” is not actually a list. It is a normal array (or just a collection of customers). In the second case, “theTable” is an object with a type “Table” (which you can easily check when using IDE), and the word “the” is just an unnecessary noise.
Good names length
In modern programming languages, long variable names are not a problem. You can create names almost without any limitations. Nevertheless the problem is that this could introduce a naming chaos in code.
A good name contains as many words as are needed to express a concept. But nothing more. Any unnecessary words make the name longer and harder to understand. Short names are good only when they describe the whole concept in the current context (it is better to say “customersInOrder” than “list” in a context of making an order).
Always code in one notation, let notation help you understand the code
Any programming technology (language) has its own “style”, called notation. A programmer should create code that matches this notation, because other programmers probably know it and use it. Let’s have a look at a bad example of code without proper notation. The code below does not fit any “standard” well-known notation (like PascalCase, camelCase, Hungarian Notation). Moreover there is a meaningless name for bool (“change”). This is a verb (describes action), but the bool value in this case describes a state, so it is better to use an adjective-like form there.
const int maxcount = 1
bool change = true
public interface Repository
private string NAME
public class personaddress
When you look at a part of code, you should know straight away what kind of element in object programming it is, just because of the notation.
For example: you see “_name” and you already know that it is a private variable in the current class. You have to always use notation, without any exception.
const int MAXCOUNT = 1
bool isChanged = true
public interface IRepository
private string _name
public class PersonAddress
Use one word per one concept. Don’t mix multiple concepts per one word
Defining concepts is always a problem. In software development process a lot of time is spend on analysis of a domain and proper naming of all elements. Hence, programmers also have difficulties with concepts.
The author of the code tried to express a concept “get the data”, using multiple words “load”, “fetch”, “get”. Only one word per concept should be used in code (in a particular domain).
A word “set” is used for 2 concepts: the first is “data loading to view”, and the second is “setting a value of object”. These concepts are not the same, so you should use different words for each one.
All code that programmers write is connected to some domain logic. To make code more understandable to anyone involved in solving a problem, it is better to use meaningful names in a domain context.
public class EntitiesRelation
When you are coding domain-specific solution, you should always use domain-specific names. In the future somebody else (not only a programmer, maybe a tester) will use your code and will be able to easily understand it in a domain context (with business logic knowledge). You should think first about the domain problem, later about how the solution is going to be implemented.
public class ProductWithCategory
Use meaningful names in their self context
Apart from the element name in code, there is always some context that the name is used within. The context is very important to understand a name, because it has additional information. Let’s have a look at a typical “address” context:
In almost all domains, a phrase “Post Code” is a part of address and it is obvious that post code cannot exists alone (unless you are developing a post code only application). So, it is unnecessary to add “address” as a part of the name. Moreover, all the information that is connected with a variable is contained in: a variable name, a class that includes this variable and a namespace that includes the class.
In object-oriented programming the best way is to design a class that represents an entity “Address”.
To sum up, as a programmer you should:
Always try to express a concept when naming any element;
Think about the length of names, they should contain only information necessary to understand intentions;
Notation helps to understand the code, so use it;
Do not mix names for concepts;
Let the names be meaningful in domain context and their self context.
Feel free to share your thoughts about this issue. If you know any other problems with naming or expressing thoughts in code that developers have, please let me know in comments below
.NET developer at Goyello. I’m especially interested in programming theory and design patterns. My big hobby is photography, so in my free time in the summer I take pictures at weddings. When I’m not coding, I enjoy cross-country mountain biking.