There’s a pandemic among programmers. Long functions, broad and nondescriptive names for functions, classes, and variable names, overly commented code, disorganized structure, and a lack of overall streamlined flow.

程序员之间大流行。 长函数，函数，类和变量名的宽泛和非描述性名称，注释过多的代码，混乱的结构以及缺乏整体精简的流程。

It’s much too often that I take a peek at someone else’s working code just to notice that I have to exert a strenuous amount of effort just to understand what it does in the first place.

我经常偷看别人的工作代码只是为了注意到我必须付出巨大的努力才能首先了解它的作用。

I have to try my best to reason about ambiguous variable names such as i, k, num, counter, etc. What type of num are we representing, and what is the purpose of the operations that surround it? What is the purpose of the counter? What is it tracking? Why is it there?

我必须尽力推断出不明确的变量名，例如i，k，num，counter等。我们代表什么类型的num ，以及围绕它的操作的目的是什么？ 柜台的目的是什么？ 跟踪什么？ 为什么在那儿？

I have to constantly jump all over the class to see how each function builds on top of the other functions around it, just to realize that the names of each function don’t really tell me anything about what the function does.

我必须不断地遍历该类，以了解每个函数如何在其周围的其他函数之上构建，只是要意识到每个函数的名称并不能真正告诉我有关该函数做什么的任何信息。

I’d even have to sometimes read paragraphs of comments that explain the purpose of what a function might do, but still, I shouldn’t have to be reading an essay to simply understand what a function does. I should be able to reason about this simply by taking a quick glance at the function.

我什至有时不得不阅读一些注释段落，这些段落解释了函数可以做什么的目的，但是，我仍然不必读一篇文章就可以简单地理解函数的作用。 我应该可以通过快速浏览一下该函数来对此进行推理。

Your code should read like a book. Just how a book is structured through paragraphs and chapters that follow a descriptive story that flows in a streamlined and progressive fashion, your code should be structured and designed in a way that I can enter into a class and be able to understand its purpose within moments of engagement. Please don’t make any developer, including yourself, who is looking at your code have to embody Sherlock Holmes in order to deduce the purpose and meaning behind what you wrote.

您的代码应该像书一样读。 就像通过描述性故事的段落和章节以精简和渐进的方式组织本书的方式一样，您的代码的结构和设计也应使我能够进入课堂并能够在瞬间理解其目的订婚。 请不要让正在查看您的代码的任何开发人员(包括您自己)必须体现Sherlock Holmes的身份，以便推断出您编写的内容的目的和含义。

What exactly should you do?

你到底应该怎么做？

通过有意义的名称进行自我注释的代码 (Self Commenting Code Through Meaningful Names)

Code should be self-commenting, which means that the names of your functions, your classes, and your variables should be so descriptive that commenting would be completely unnecessary. A sure sign of poorly written code is matched with its need to have comments.

代码应该是自注释的，这意味着函数，类和变量的名称应具有描述性，以至于注释完全没有必要。 确定代码写得不好的肯定标志与需要注释的要求相匹配。

Stop abbreviating names (unless the translation of the abbreviation is blatantly obvious), stop using letters as variables, and start writing names with the intent to describe exactly what that function’s or variable’s purpose is. The names must be both intention-revealing and pronounceable.

停止缩写名称(除非明显地翻译缩写)，停止使用字母作为变量，并开始写名称以确切描述该函数或变量的用途。 名称必须既有意图，又要发音。

In essence, don’t just write code that only a computer will read. Write code that is human-readable as well. This is extremely simple in practice, but you’ll find that you will become a lot more thoughtful about the naming of everything you write and it’ll allow you to better reason about the intent of what you are programming which ultimately will influence fluid production of your code.

本质上，不要仅仅编写仅计算机可以读取的代码。 编写易于理解的代码。 这在实践中非常简单，但是您会发现您对所写内容的命名要更加周到，并且可以让您更好地思考编程的意图，最终将影响流体生产您的代码。

“A long descriptive name is better than a short enigmatic name. A long descriptive name is better than a long descriptive comment.”

“长的描述性名称比短的神秘性名称更好。 具描述性的名称胜于具描述性的评论。”

― Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship

― Robert C. Martin，“ 清洁代码：敏捷软件Craft.io手册”

If you still don’t understand, here is a simple example of me populating a picklist with values (language is in Salesforce’s Apex, but you should still understand the gist of what I’m trying to convey):

如果您仍然不明白，这是一个简单的示例，说明我使用值填充选择列表(语言在Salesforce的Apex中，但您仍应了解我要传达的内容的要旨)：

public static final Integer YEARS_IN_SCHOOL = 12;public static final Integer GRADUATION_MONTH = 6;private List<Integer> getGradYearPicklistValues() {    List<Integer> gradYearValuesList             = new List<Integer>();    Integer earliestYearInPicklist = Date.today().year();    Integer latestYearInPicklist             = earliestYearInPicklist + YEARS_IN_SCHOOL;    if (Date.today().month() >= GRADUATION_MONTH) {        earliestYearInPicklist += 1;        latestYearInPicklist += 1;    }    for (Integer year = earliestYearInPicklist; year <= latestYearInPicklist; year++) {        gradYearValuesList.add(year);    }    return gradYearValuesList;}

As you can see, I use very descriptive variable names and use descriptive function names so that we know exactly the purpose of each variable, and what the purpose this function serves. It becomes very easy for other developers to reason exactly what this function is doing.

如您所见，我使用了描述性很强的变量名和描述性的函数名，以便我们确切地知道每个变量的用途以及该功能的作用。 其他开发人员可以很容易地确切推断此功能的作用。

有组织的自上而下的代码结构 (Organized Top-Down Code Structure)

The way you format your code serves as a direct indicator of the amount of thoughtfulness, attention to detail, and effort put into writing it. When others come to review your code, you want them to be struck with the impressive neatness, orderliness, and readability of the code. The last thing you want is to deliver a monolithic wall of scrambled, unorderly code that at a glance looks like it was written while being hammered off of White Claws and Bud Lights. This only leads to the conclusion that no thought or attention to detail was put into the code whatsoever, which ultimately reflects poorly on you.

格式化代码的方式直接表明了代码的考虑程度，对细节的关注以及编写代码所付出的努力。 当其他人来审阅您的代码时，您希望他们被代码令人印象深刻的整洁，有序和可读性所打动。 您需要做的最后一件事是提供一堆混乱的，无序的代码墙，一眼看上去就像是被白爪子和芽光打碎时所写的那样。 这只能得出这样的结论，即代码中没有考虑或关注细节，最终对您的反映很差。

The way you should format your code is best explained by the Newspaper Metaphor in Robert C Martin’s Clean Code (a book all programmers should read, by the way):

罗伯特·C·马丁(Robert C Martin)的“ 干净代码”中的报纸隐喻最好地解释了格式化代码的方式(顺便说一下，所有程序员都应该读这本书)：

“Think of a well-written newspaper article. You read it vertically. At the top, you expect a headline that will tell you what the story is about and allows you to decided whether it is something you want to read. The first paragraph gives you a synopsis of the whole story, hiding all the details while giving you the broad-brush concepts. As you continue downward, the details increase until you have all the dates, names, quotes, claims, and other minutiae. We would like a source file to be like a newspaper article.”

“想想一篇写得好的报纸文章。 您垂直阅读。 在顶部，您希望看到一个标题，该标题将告诉您故事的内容，并让您确定是否要阅读。 第一段为您提供了整个故事的提要，隐藏了所有细节，同时为您提供了广泛的概念。 随着您继续向下操作，详细信息会不断增加，直到您拥有所有日期，名称，报价，声明和其他细节为止。 我们希望源文件像报纸上的文章。”

What does this tell us? Our class name is our headline — it’s going to describe the contents of what we can find inside the class. At the top of the class is where we are going to find our high-level concepts and algorithms and as we traverse down the class we should be seeing the details increase and increase until we find ourselves at the lowest level function.

这告诉我们什么？ 我们的班级名称是我们的标题-它将描述我们在班级内可以找到的内容。 在课程的顶部，我们将找到高级概念和算法，并且在遍历课程时，我们应该看到细节越来越多，直到我们发现自己处于最低级别的功能为止。

How do we follow this structure? Well, it’s very easy, actually. We essentially want the most important details to come first and express those concepts downward with the most precise and concise details. Any function that is called should be placed right below the function that is doing the calling. If a function is too large (my rule of thumb is to keep functions below 20–25 lines), break it up into smaller bite-size functions that provide complete clarity about what a few lines of code are processing. Normally large functions indicate that function is doing too much and that it is starting to get messy, so that’s why we do this. To be more descriptive. To be more neat and orderly.

我们如何遵循这种结构？ 好吧，实际上非常简单。 我们本质上希望最重要的细节放在首位，并以最精确和简洁的细节向下表达这些概念。 任何被调用的函数都应放在进行调用的函数的正下方。 如果函数太大(我的经验法则是将函数保持在20–25行以下)，则将其分解为较小的小位函数，以提供有关要处理的几行代码的完整信息。 通常，大型函数表示该函数执行过多操作，并且开始变得混乱，因此这就是我们这样做的原因。 更具描述性。 更加整齐有序。

带走 (Takeaway)

Programming is very mentally challenging work as it is, and I understand how the importance of great readable code can easily be ignored given that we become so engulfed in the act of programming that we completely forget about the art and design of it. Take a step back and think about what you’re doing — the intention, the neatness, and its readability. It’ll not only help you understand the code you write more but help others understand it better as well. Ultimately, you’ll become a better and more revered programmer because of it. Who knows, you may get some praise for producing something beautiful.

编程实际上是一项在精神上具有挑战性的工作，而且我理解，既然我们被编程的行为所深深吸引，以至于我们完全忘记了它的艺术和设计，那么如何轻易地忽略优质可读代码的重要性。 退后一步，思考一下您在做什么—意图，简洁性及其可读性。 它不仅可以帮助您理解您编写的代码，还可以帮助其他人更好地理解它。 最终，您将因此成为一个更好，更受人尊敬的程序员。 谁知道，您可能会因生产精美的东西而获得称赞。