Hello, Habr!
How often did you have that you or your colleagues could not describe your own code with a couple of phrases?
I bring to your attention a translation of the article "How to write easily describable code" by Cedd Burge , in which he shares his advice on how to avoid such situations.
When code is hard to describe with words, most people have to use imagination to do this. For this reason, mental energy is wasted and the risk of errors in interpreting code is increased. Different people will still perceive the words in their own way, which will lead to confusion when discussing the code.
As a rule, such discussions become fertile ground for errors that appear due to misunderstandings, and correcting these errors often leads to the appearance of new errors for the same reasons. In the end, we get an incomprehensible code that no one wants to work with.
Indescribable Code Example
You might think that code is just a written language. If the code looks simple, then it can be easily read, described and understood. However, this is not always the case.
The following general decision determines whether a year is a leap year.
(divisibleBy(4) and not divisibleBy(100)) or divisibleBy(400)
This is simple code. It calls functions 3 times, has 3 operators (and, or, no) and two levels of nesting.
But I think that if you are given one second to describe this algorithm using words, you will have difficulty.
Maybe “a year is a leap year if it is divisible by 4 and not divisible by 100, or divisible by 400”?
The problem is that in words, unlike code, there are no brackets. Therefore, it is difficult to adequately describe the condition in words and whether "refers to or is divided by 400" refers to "is divided by 4" or to "is not divided by 400". To work around this problem, you can specify brackets with your hand or take longer pauses between conditions, but the probability of an error will still remain large.
Refactoring the described code
We can first describe the conditions with words and only then reduce them, making them as clear and concise as possible. Let's start like this:
"400 years is a unique case. If a year is divisible by 400, then this is a leap year. 100 years is also a unique case. If a year is divisible by 100, then this is not a leap year unless it is divisible by 400, the priority for the special case is “400 years.” If there are no special cases, then this year is a leap year, provided that it is divided by 4 ”.
It sounds understandable, but not concise, so we will shorten the text a little:
“If the year is divided by 400, then it is a leap year. If it is divided by 100, then this is a normal year, but when divided by 4, this is a leap year. "
If we turn these words into code, we get something like the following:
if divisbleBy(400): return LeapYear elif divisbleBy(100) return NormalYear elif divisbleBy(4): return LeapYear else: return NormalYear
conclusions
Difficult to understand code is commonplace for almost all programmers. We will help ourselves and our colleagues if we write code that is easily described in words.
And most importantly, writing code in this way is easiest, since there is no vain mental effort. The “trick” is that the algorithm is first described by the words that will later be used to write the code.
In many organizations, code has already begun to be described in words in acceptance tests or user stories, which can improve productivity.