如何让代码更易于维护_如何编写易于描述的代码

如何让代码更易于维护

When code is not describable using words, most people have to do some mental mapping to turn it in to words. This wastes mental energy, and you run the risk of getting the mapping wrong. Different people will map to different words, which leads to confusion when discussing the code.

当无法使用单词描述代码时，大多数人必须进行一些思维导图才能将其转换为单词。 这浪费了精力，并且冒着错误绘制映射的风险。 不同的人会映射到不同的单词，这在讨论代码时会引起混乱。

This is usually a fertile breeding ground for bugs born out of miscommunication / misunderstanding, and fixing these bugs often introduces new ones, for the same reasons. In the end it becomes code that no one really understands or wants to touch.

通常，这是因沟通不畅/误解而产生的错误的沃土，出于相同的原因，修复这些错误通常会引入新的错误。 最后，它变成了没有人真正理解或想要触摸的代码。

不可描述的代码示例 (Example of undescribable code)

It is easy to think that code is already a written language. If it looks simple, it should be easy to read, speak and listen to. However, this is not always the case.

容易想到代码已经是一种书面语言。 如果看起来很简单，则应该易于阅读，说话和听取。 然而，这并非总是如此。

Below is a common solution to deciding whether a year is a leap year.

以下是确定一年是否为leap年的常见解决方案。

(divisibleBy(4) and not divisibleBy(100)) or divisibleBy(400)

This is not overly complicated code. It calls a functions 3 times, has 3 operators (and, or, not), and has two levels of nesting.

这不是过于复杂的代码。 它调用一个函数3次，具有3个运算符(“和”或“非”)，并且具有两个嵌套级别。

However, if you take a second to try and describe the algorithm in words I think you will find it to be a struggle.

但是，如果您花一点时间尝试用语言来描述算法，我想您会发现它很麻烦。

Maybe “A year is leap year if it is divisible by 4 and not divisible by 100, or divisible by 400”?

也许“如果年份可以被4整除而不能被100整除，或者被400整除，那么它就是leap年”？

The trouble with this is that the code has brackets, but the words do not. So they cannot adequately describe the condition, and whether “or divisible by 400” applies to “divisible by 4” or “not divisible by 400”. You could try some hand waving and gesturing to get around this, or vary the length of pause between the statements, but hopefully it’s obvious that there is a lot of potential for error.

这样做的麻烦是代码带有方括号，但单词却没有。 因此，他们无法充分描述条件，并且“或被400整除”适用于“被4整除”还是“未被400整除”。 您可以尝试挥手示意，以解决此问题，或者更改语句之间的停顿时间，但希望很明显，很可能会出现错误。

重构为可描述的代码 (Refactoring to describable code)

Instead we can start by describing the condition with words, and then make the words as clear and concise as possible. We might start with this:

相反，我们可以先用单词描述条件，然后使单词尽可能清晰明了。 我们可以从以下开始：

“400 years is a special case. If a year is divisible by 400, then it is a leap  year. 100 years is also a special case. If a year is divisible by 100 then it isn’t a leap year, unless it is also divisble by 400, the 400 year special case takes priority. If there are no special cases, then the year is a leap year if it is divisible by 4.”

“ 400年是一个特例。 如果一年可以被400整除，那么它就是a年。 100年也是一个特例。 如果一年可以被100整除，那么它就不是a年，除非它也可以被400整除，否则400年特殊情况优先。 如果没有特殊情况，则该年份是可以被4整除的a年。”

This is clear, but isn’t concise, so we would probably want to shrink it a bit:

这很清楚，但不够简洁，因此我们可能要缩小一点：

“If a year is divisible by 400, then it is a leap year. Otherwise if it is divisible by 100 then it is a normal year, otherwise it is a leap year if it is divisible by 4.”

“如果一年可以被400整除，那么它就是a年。 否则，如果它可以被100整除，则它是正常年份；否则，如果它可以被4整除，则它是a年。”

If we turn these words in to code, we probably get something like the following:

如果将这些单词转化为代码，我们可能会得到如下所示的内容：

if divisbleBy(400):
		return LeapYear
	elif divisbleBy(100)
		return NormalYear
	elif divisbleBy(4):
		return LeapYear
	else:
		return NormalYear

结论 (Conclusions)

Hard to understand code is a daily occurrence for virtually all programmers. We can help ourselves and our co-workers by writing code that is easy to describe in words.

几乎所有程序员都每天都难以理解代码。 我们可以通过编写易于用语言描述的代码来帮助自己和我们的同事。

And the great thing is that doing so is actually easier than writing code any other way, as there is no mental mapping / wasted mental effort. The only “trick” is to describe the algorithm in words, and then write code to match the words.

很棒的事情是，这样做实际上比任何其他方式编写代码都容易，因为没有精神上的映射/精神上的浪费。 唯一的“技巧”是用单词描述算法，然后编写代码以匹配单词。

In many organisations, the algorithm will already be described in words, as part of acceptance tests or user stories, which will improve productivity even further.

在许多组织中，作为验收测试或用户案例的一部分，已经用语言描述了该算法，这将进一步提高生产率。

翻译自: https://www.freecodecamp.org/news/writing-describable-code/

如何让代码更易于维护