Good source code meets two important criteria. First, it is correctly written and achieves the specified end result according to the specification. Second, it is easy for other programmers, aside from its author, to read and append.
Understandable source code that is well-tested facilitates easy refactoring, expansion, and modification of the system. Such code forms a solid base where programmers are not afraid to make changes, and those changes are made quickly.
Writing code is a social activity—it is done by teams of people. The source code written by one programmer does not exist in isolation. It is read and often appended by other programmers. To modify it, they first need to understand it.
What Happens If the Code Is Not Well Written?
Errors in the code are relatively easy to find. However, unreadable and incomprehensible code may go unnoticed for a long time. Until another programmer, trying to fix a bug or add new functionality, encounters it and tries to understand what this source code does before appending it. If they do not understand it correctly and unambiguously, a series of problems will follow. Incomprehensible code might be used for something it was not intended for, and some functionality of the program might stop working.
This starts a pattern leading to an increasing degradation of code quality. The programmer trying to append incomprehensible code loses a lot of time trying to understand how the code works. Instead of making it clearer and easier to read, they make very small changes (to avoid breaking something), and the result is even more incomprehensible code. The next programmer loses even more time trying to understand what the code does, gets frustrated, rewrites the code or rewrites it entirely. Thus, new errors appear or old ones are rewritten. The team’s work slows down, development halts.
What Does Understandable Source Code Mean and How to Achieve It?
Probably every programmer has their answer to this question. For Code Academy and CODIX, this means code that is easy to read and clear, which can be easily appended and modified by other programmers, besides its author. You can achieve this, and we will teach you how.
Principles to Help You Write Understandable Source Code
There are countless principles, but we will stop only at the most basic ones:
- Single Responsibility. All building blocks of the code—classes, methods, variables—follow the principle of “one element does one single thing.” This way, it is easier for the reader to understand exactly what that thing is. Accordingly, it is clearer, in case of a problem, which part of the code needs to be changed.
- Good Structure. The code is easy to read if it is logically structured and consistent—with functions, classes, modules.
- Expressive Names. The names of classes, functions, and variables facilitate reading and understanding the source code. Keep in mind that code with good names is the fruit of much effort by programmers who have devoted a lot of time to achieving them.
- Simplicity and Specificity. Software is complex enough. The code it is written in must be as simple and specific as possible. Programmers do not use much imagination when writing and look to avoid unnecessary complications. Functions are usually short and easy to read. Classes should not be too large either.
- Comments Explain “Why,” Not “How.” Most code should be self-explanatory. And comments should only fill in potential gaps.
- Refactoring. Codebases grow. When a simple class gains more responsibilities, it also grows and becomes more complex. Understandable bases are due to constant refactoring. The new complex class can be split into parts or changed so that it remains easy to read.
- Well Tested. Well-tested code can be changed easily and without fear that something in it might stop working. Testing with automated tests helps the code stay understandable. Without tests, refactoring becomes very risky, and programmers might stop doing it. With tests, there’s no reason not to make even significant and risky refactorings, thanks to which the code remains understandable and easy to read.
The best check to see if your source code is readable is to show it to other programmers for their opinion. Ask them to share whether they find it clear. Let them ask you questions. If the code is understandable, there will be few or no questions. Pay special attention if you notice that someone has completely misunderstood what you wrote and asks many questions. Every question or ambiguity opens opportunities for you to make your source code more understandable.
If both you and other programmers agree that the source is understandable, then you are on the right path. The principles listed above will help you make your code even more understandable and clear. Focus on making your code clear for you and the people you work with.
There are many sources of information on how to write understandable code and ways to make the code clearer. We recommend this article.