This article is proudly presented by Foreign IT Review (www.aqee.net)
Beginner programmers often spend a lot of time learning programming languages, syntax, tricks, and how to use 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 techniques and tools — it is about creating corresponding solutions for specific problems within a particular domain, and programmers achieve this through mutual collaboration. Therefore, it is very important that you can precisely express your ideas through code so that others can understand your intent by reading it.
Let us first look at a quote from the masterpiece Clean Code by programming master Robert C. Martin:
“The purpose of comments is to compensate for the code’s own failure to express itself.”
This statement can be simply understood as if your code needs comments, it is most likely poorly written. Likewise, if you cannot fully express your thought process on a problem or algorithm in code without comments, that is a sign of failure. Ultimately, this means you need to use comments to clarify part of your thinking that is not apparent in the code itself. Good code allows anyone to understand it without needing any comments at all. Good coding style embeds all the information needed to understand the problem within the code itself.
In programming theory, there is a concept called “self-documenting source code.” A common self-documenting mechanism for code is to follow some loosely defined naming conventions for variables, methods, and objects. The main purpose of doing this is to make source code easier to read and understand. As a result, it also becomes easier to maintain and extend.
In this article, I will give some examples to illustrate what constitutes “bad code” and what constitutes “clean code.”
Names Should Reveal Intent
How to name things has always been one of the hardest problems 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 below:
Bad code:
1.int d;2.// days3.int ds;4.int dsm;5.int faid;“d” could mean anything. The author used a comment to indicate his intent, but did not choose to express it through code. And “faid” can easily be misinterpreted as an ID.
Clean code:
1.int elapsedTimeInDays;2.int daysSinceCreation;3.int daysSinceModification;4.int fileAgeInDays;Avoid Misleading Information When Naming
Wrong information is worse than no information at all. Some programmers like to “hide” important information, and sometimes they also write code that misleads people.
Bad code:
1.Customer[] customerList;2.Table theTable;The variable “customerList” is not actually a list. It is a plain array (or a customer collection). In addition, “theTable” is an object of type Table (you can easily discover its type using an IDE), and the word “the” is an unnecessary distraction.
Clean code:
1.Customer[] customers;2.Table customers;Names Should Have Appropriate Length
In high-level programming languages, the length of variable names is usually not very restricted. Variable names can be almost any length. Nevertheless, this can also make code annoying.
Bad code:
1.var theCustomersListWithAllCustomersIncludedWithoutFilter;2.var list;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. The shorter the name, the better, provided that it can express the complete meaning within its context (in an order placement scenario, “customersInOrder” is better than “list”).
Clean code:
1.var allCustomers;2.var customersInOrder;Keep Coding Conventions Consistent So They Help Understand the Code
All programming techniques (languages) have their own “style,” called coding conventions. Programmers should follow these conventions when writing code, because other programmers also know them and write in this style. Below we look at an example of bad code without an obvious convention. The code below does not follow well-known “coding conventions” (such as PascalCase, camelCase, Hungarian notation). Even 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 here.
Bad code:
1.const int maxcount = 12.bool change = true3.public interface Repository4.private string NAME5.public class personaddress6.void getallorders()When looking at only part of the code, you should immediately understand what type it is, just by looking at its naming convention.
For example: when you see “_name,” you know it is a private variable. You should use this naming convention everywhere, without exception.
Clean code:
1.const int MAXCOUNT = 12.bool isChanged = true3.public interface IRepository4.private string _name5.public class PersonAddress6.void GetAllOrders()Use the Same Word for the Same Concept When Naming
Defining concepts is difficult. During the software development process, a lot of time is spent analyzing business scenarios and thinking about the correct definitions for all the elements involved. These concepts are always a headache for programmers.
Bad code:
1.//1.2.void LoadSingleData()3.void FetchDataFiltered()4.Void GetAllData()5.//2.6.void SetDataToView();7.void SetObjectValue(int value)First:
The author of the code tried to express the concept of “get the data,” but used multiple words “load,” “fetch,” and “get.” Use only one word for one concept (within the same scenario).
Second:
The word “set” is used in two concepts: the first is “data loading to view,” and the second is “setting a value of an object.” These are two different concepts, so you should use different words.
Clean code:
1.//1.2.void GetSingleData()3.void GetDataFiltered()4.Void GetAllData()5.//2.6.void LoadDataToView();7.void SetObjectValue(int value)Use Words Related to the Business Domain When Naming
All code written by programmers is connected to business domain scenario logic. To help everyone involved with the problem understand it better, the program should use names that are meaningful within the domain context.
Bad code:
1.public class EntitiesRelation2.{3.Entity o1;4.Entity o2;5.}When writing code for a particular domain, you should always consider using names that are related to that domain. In the future, when another person (not just 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). You should first consider the business problem, and then how to solve it.
Clean code:
1.public class ProductWithCategory2.{3.Entity product;4.Entity category;5.}Use Words That Are Meaningful in a Specific Context When Naming
Names in code 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:
1.string addressCity;2.string addressHomeNumber;3.string addressPostCode;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 environment, a namespace, a class.
In object-oriented programming, an “Address” class should be used here to express this address information.
Clean code:
1.class Address2.{3.string city;4.string homeNumber;5.string postCode;6.}Summary of Naming Conventions
To summarize, as a programmer, you should:
- Use names to express concepts
- Pay attention to name length — a name should only contain 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 within their context