编码最佳实践 (Coding Best-Practices)

In the following section, I will introduce the topic at hand, giving you a sense of what this post will cover, and how each argument therein will be approached. Hopefully, this will help you decide whether it will be worth investing your time, in reading the rest of the post. However, if you would rather get to the crux of the post fast, skip the following section. The Good Stuff awaits you there!

在下一节中，我将介绍手头的主题，使您对这篇文章将涉及的内容以及如何处理其中的每个论点有所了解。 希望这可以帮助您决定是否值得花时间在阅读本文的其余部分。 但是，如果您希望快速了解帖子的症结，请跳过以下部分。 好东西在那等着你！

Do you want to know the #5 simple tips that you must follow to become a great coder? Or, the secret sauce to upskilling your coding abilities, and landing that dream job in a tech giant?

您是否想知道成为一名优秀编码员必须遵循的＃5个简单技巧？ 或者，秘诀在于提高您的编码能力，并让梦想中的工作进入科技巨头？

— If so, stop reading.

—如果是这样，请停止阅读。

For, today I refuse to let you in on these powerful industry secrets. And, the reason I am doing this, is three-fold.

今天，我拒绝让您了解这些强大的行业秘密。 而且，我这样做的原因有三点。

1.没有这样的秘密。 (1. There are no such secrets.)

And if there are, I am out of the club as well. Sigh!

如果有的话，我也将退出俱乐部。 叹！

2.编写好的代码的能力对他人的帮助远大于对您的帮助 (2. Ability to write good code helps others more than it helps you)

If you want to learn to write good code, so as to improve your resume, or be able to complete your next deliverable, then this is not the skill to learn. Writing good code is a team skill; it helps your peers, and if they practice it, it helps you. Simply put, writing good code, is the polite thing to do.

如果您想学习编写出色的代码，以提高履历，或者能够完成下一份交付品，那么这不是学习的技能。 编写好的代码是一种团队合作精神； 它可以帮助您的同龄人，如果他们实践它，则可以为您提供帮助。 简单地说，编写好的代码是有礼貌的。

The only time when it can help you directly, is if you happen to come back to a piece of code that you had written a long long time ago!

它唯一可以直接为您提供帮助的时间是，如果您碰巧回到了很久以前编写的一段代码！

3.好的代码是以用例为中心的术语。 (3. Good code is a use-case centric term.)

Depending on the purpose of the code, the yardstick by which we measure its goodness will change. And, while I will touch upon a few different use cases, as part of this post, they will be primarily explored to add some context and some contrast, to the main use-case that I want to focus on for today.

根据代码的目的，我们衡量其优劣的标准将会改变。 而且，尽管我将介绍几个不同的用例，但作为本文的一部分，将主要探讨它们， 以便为我今天要重点关注的主要用例添加一些上下文和对比。

A large and sufficiently complex code-base, that is meant to be progressively worked on by many authors, across multiyear roadmaps, whose production environments are hosted in and have dependencies on elastic web services, and whose end customer is a human.

大型且足够复杂的代码库，旨在跨许多年的路线图逐步被许多作者使用，其生产环境托管在其中并依赖于弹性Web服务，并且最终用户是人类。

Why we choose to restrict ourselves to these parameters will become self-evident as we explore further. But for now, let’s introduce a simple and famous thought, on which we will base the rest of this post.

我们为什么选择限制自己使用这些参数，这将在我们进一步探索时变得不言而喻。 但是现在，让我们介绍一个简单而著名的思想，我们将在本文的其余部分作为基础。

“Code is read far more often than it is written”

“代码被读取的次数远多于代码被写入的次数”

A very simple and to some extent a very obvious observation, but one that carries with it a significant insight. — Optimise code for human read operations.

这是一种非常简单的观察，在某种程度上是非常明显的观察，但同时也带来了重要的见识。 — 优化代码以进行人工读取操作。

When we first learn to code, we write our Hello World programs, and slowly crawl on to simple data structures and algorithms. We are then introduced to the Big-O(s), and learn to think in terms of time and space complexity. And we carry this mental model of how to approach code throughout our academic years and then try to use the same to develop software products in our workspaces.

第一次学习编码时，我们编写Hello World程序，然后慢慢爬到简单的数据结构和算法。 然后将我们介绍给Big-O，并学习如何根据时间和空间复杂性进行思考。 而且，我们在整个学年中都采用了这种思维方式，即如何处理代码，然后尝试将其用于在工作区中开发软件产品。

Now this is a sound way to approach code, if our aim is to write code that the compiler/interpreter understands. For, in this approach, we become comfortable with the concept of global state, usage of setters everywhere, and writing any obscure complex logic (from a human perspective), as long as it generates byte codes that the Interpreter can crunch through faster.

现在，如果我们的目标是编写编译器/解释器可以理解的代码，那么这就是一种处理代码的好方法。 因为在这种方法中，我们对全局状态的概念，到处使用设置器以及编写任何晦涩复杂的逻辑(从人类的角度来看)感到满意，只要它生成解释器可以更快处理的字节码即可。

Now, we should not ignore the good that this approach brings to the table. Our programs work, take as little a space as possible, and runs as fast as possible. And, if code once written, was meant to be set in stone, this approach would have been the panacea to all of our woes, and we would live happily ever after. But the real world use case, for which we are trying to write good code, is far more fluid, and is far more messy.

现在，我们不应该忽略这种方法带来的好处。 我们的程序可以正常工作，占用尽可能少的空间，并尽可能快地运行。 而且， 如果代码一旦被写成是一成不变的 ，那么这种方法将成为我们所有祸患的灵丹妙药，从此以后我们将过上幸福的生活。 但是，现实生活中的用例(我们正在尝试为其编写良好的代码)更加流畅，而且更加混乱。

And in the messy real world, where Murphy’s law reigns supreme, this approach brings with it a glaring tradeoff.

在墨菲法则凌驾于凌乱的现实世界中，这种方法带来了明显的折衷。

Buggy代码库，没人想碰。 (A Buggy Codebase, that no one wants to touch.)

We all know of those codebases, that we had worked on at some point of time, and would make a hundred excuses to avoid working on again. The reasons for this are many, but some of the most common ones, and the ones which have given me night terrors at one point or another, are.

我们都知道我们曾经在某个时间点上工作过的那些代码库，并且会以一百个借口避免再次工作。 造成这种情况的原因很多，但有一些最常见的原因，以及使我一夜之间惊恐的原因。

一切都已连接。 (Everything is connected.)

The code works (well, 7/10 times it works), but if you change a private method in an inner module meant for doing one thing, it breaks some existing feature in a completely different module, that does something completely different.

该代码可以工作(效果是它的7/10倍)，但是如果您在内部模块中更改用于执行某项操作的私有方法，则会破坏完全不同的模块中的某些现有功能，从而导致功能完全不同。

每个人都很忙。 (Everyone has a side hustle.)

Throughout the codebase, methods change their input parameters, and have more side-effects than snake oil. This makes it impossible to understand what is happening, without having to read the entire flow, down to its lowest details. Looking at you, System.out.println()[1][2] .

在整个代码库中，方法更改其输入参数，并且比蛇油具有更多的副作用。 这使得无法了解正在发生的事情，而不必阅读整个流程，直到最底层的细节。 看着你， System.out.println() [1] [2]。

将调试器交给我，好吗。 (Pass me the debugger, will you.)

Recently I was solving a competitive coding problem. I ended up with two solutions, a (somewhat) human readability optimised one, and a compiler optimised one.

最近，我正在解决一个竞争性编码问题。 我最终提出了两种解决方案，一种(某种程度上)人类可读性优化的解决方案，以及一种编译器优化的解决方案。

Here is the generic problem statement.

这是一般问题说明。

Now let’s implement the compiler optimised one.

现在让我们实现编译器优化的一个。

The code is small, and very efficient O(n). Great. But how does it work? Not that simple, right? You’ll have to do a dry run or fire up the debugger before you start to have an understanding of how this code works.

该代码很小，并且效率非常高O(n)。 大。 但是它如何工作？ 不是那么简单，对吧？ 在开始了解此代码的工作方式之前，您必须进行空运行或启动调试器。

Now imagine that.

现在想象一下。

This code powers your customers’ logistics systems, and there is a bug. Every minute you don’t fix it thousands of your customers won’t know if they have enough gas left to complete the journey. Would you want to be the one in charge of fixing the bug asap, in a code like this?

该代码为您的客户的物流系统提供了动力，并且存在一个错误。 每分钟您不修复它，成千上万的客户将不知道他们是否有足够的汽油来完成旅程。 您想成为像这样的代码中尽快修复错误的负责人吗？

Now again image that.

现在再次成像。

When this code was written, the price of gas was cheap. So our customers did not care about the price, as long as they could complete their journey. Recently there has been a trade war between the country of operation and its oil and gas trading partner. Suddenly price is an important variable. Where should we put this logic?

编写此代码时，汽油价格便宜。 因此，只要他们可以完成旅程，我们的客户就不在乎价格。 最近，运营国与其油气贸易伙伴之间发生了贸易战。 价格突然是一个重要的变量。 我们应该把这个逻辑放在哪里？

Now you may say that, “Hey, let the person who wrote this in the first place, take care of this requirement”. — Well that person, might have switched teams, changed companies, or went on to become a Pokemon trainer. Who knows.

现在您可能会说， “嘿，首先让撰写此内容的人注意这个要求” 。 —好吧，这个人可能换过团队，更换了公司，或者继续成为Pokemon培训师。 谁知道。

The Codebase is the shared inheritance of the entire team/community. The Codebase should be immemorial. The developers should be fungible. If my absence means that the features I have developed become orphaned, then my code is a liability to that inheritance.

代码库是整个团队/社区的共享继承。 该代码库应该是不朽的。 开发人员应该是可替代的。 如果我的缺席意味着我开发的功能变得孤立，那么我的代码就是这种继承的责任。

So while this code is an asset (small, light and fast) for the present use case, the slightest of tremors, can turn it into a liability (difficult to understand, fix and expand).

因此，尽管此代码是当前用例的一种资产(小巧，轻便，快速) ，但丝毫震动却可以将其转变为责任(难以理解，修复和扩展) 。

And in our messy real world, remember Murphys Law,

在我们凌乱的现实世界中，请记住墨菲定律，

“Anything that can go wrong, will go wrong”[3]

“任何可能出错的地方，都会出错” [3]

Now let us turn to a more human readability optimised solution.

现在让我们转向一个更具人类可读性的优化解决方案。

Ok, so let’s see what happens here.

好的，让我们看看这里发生了什么。

• For each station, starting from the first, evaluate whether we can complete the route from there, and filter out all stations where we can’t.
  对于每个站点，从第一个站点开始，评估我们是否可以从那里完成路线，并过滤掉所有我们无法到达的站点。
• Among the filtered stations, find the station with the minimum index.
  在过滤的站点中，找到索引最小的站点。
• If no stations meet the criteria, we inform that the route can’t be completed.
  如果没有车站符合条件，我们会通知您路线无法完成。

We don’t even need to know what CircularRouteDetails does or how we evaluate whether the route can be completed, to understand at a high level what we are doing.

我们甚至不需要知道 CircularRouteDetails没有或我们如何评估路由是否就可以完成，以高层次我们在做什么了解。

Now if I as a reader want to know how some low level details work, i can dive into the methods and figure it out. So though the codebase is bigger, I as a reader can simply pick and choose what i want to know. In the first, I would be fumbling through a ten page dictionary that prints words in random order, and in the second, I will be methodically proceeding through a thousand page one, that follows a strict alphabetical ordering.

现在，如果我作为读者想知道一些底层细节的工作原理，那么我可以深入研究这些方法并加以解决。 因此，尽管代码库更大，但作为读者，我可以选择我想知道的内容。 在第一篇中，我将摸索一本十页的字典，该词典以随机顺序打印单词，而在第二篇中，我将有条不紊地浏览一千页，并遵循严格的字母顺序。

The ability to do is a very powerful one, and one that is sadly under-appreciated.

做事的能力是一种非常强大的能力，而令人遗憾的是它没有被重视。

In this solution, the concepts and responsibilities are separated out into encapsulated portions of the code. Furthermore, the naming of the methods, classes and fields have been chosen with care to aid in the easy identification of said responsibilities. (The above code can be further improved, I agree, but you get the point). So now when a bug creeps in, I don’t need to fumble about the entire codebase, I can go the portion where it is most likely that the issue is emanating from and fix it.

在此解决方案中， 概念和职责分离为代码的封装部分 。 此外， 已经仔细选择了方法，类别和字段的命名，以帮助容易地识别所述职责 。 (我同意，上面的代码可以进一步改进，但是您明白了) 。 因此，现在，当一个bug出现时，我不需要摸索整个代码库， 我可以去查找最有可能产生此问题的部分并加以解决。

If you want to checkout at the entire codebase, See here

如果要在整个代码库中签出，请参见此处

But wait, I hear you ask,

但是等等，我听到你问，

“Hmm, I get your point. But the second solution is slower, and so on a day-to-day basis you will deliver slower results to your customers. Also, it will incur more hardware costs.”

“嗯，我明白你的意思。 但是第二种解决方案速度较慢，因此在日常工作中，您将为客户提供较慢的结果。 而且，这将导致更多的硬件成本。”

All valid points, and I am glad you asked them!To answer this, I will redirect you to our use case definition. So let me reiterate.

所有有效点，很高兴您提出来！要回答此问题，我会将您重定向到我们的用例定义。 因此，我重申一下。

A large and sufficiently complex code-base, that is meant to be progressively worked on by many authors, across multiyear roadmaps, whose production environments are hosted in and have dependencies on elastic web services, and whose end customer is a human.

大型且足够复杂的代码库，旨在跨多年的路线图被许多作者逐步开发，其生产环境托管在其中并依赖于弹性Web服务，并且最终用户是人类。

So now with this use case as the context, let us answer this question in detail.

因此，现在以这个用例为背景，让我们详细回答这个问题。

1.速度 (1. Speed)

“But the second solution is slower, so on a day to day basis you will deliver slower results to your customers”

“但是第二种解决方案速度较慢，因此在日常工作中，您将为客户提供较慢的结果”

For the sake of measurable efficiency differences, let us assume that the first solution takes O(n) and the second solution takes O(n²). The number of gas stations is 1000 and the operation pertaining to each step takes 1µs. Hence the first solution will take 1ms and the second will take 1s. Definitely, an enormous difference in electronic terms, but hardly noticeable from a human perception point of view. A human being will hardly be able to tell whether a page loads in 1ms or 1s. And what was a core requirement of our use case? — “and whose end customer is a human.”

为了可测量的效率差异，让我们假设第一个解决方案采用O(n) ， 第二个解决方案采用O(n²) 。 加油站的数量为1000 ， 与每个步骤有关的操作耗时1µs 。 因此， 第一个解决方案将花费1ms ， 第二个 解决方案 将花费1s 。 绝对是电子术语上的巨大差异，但从人类感知的角度来看几乎不明显。 人们几乎无法分辨页面是在1ms还是1s内加载的。 我们用例的核心要求是什么？ - “并且其最终客户是人类。”

But this explanation is a tad disingenuous. It works because of the values I chose. What if there were 10⁶ gas stations? Then the first solution will take 1s and the second will take 10⁶s. 10⁶s will definitely get noticed by a human user. Here, the first solution is defiantly the better one. Or is it?

但是，这种解释是不正确的。 由于我选择的值，它起作用。 如果有10个加油站怎么办？ 那么第一个解决方案将花费1s ， 第二个 解决方案 将花费10s 。 使用者肯定会注意到10秒钟。 在这里，第一个解决方案绝对是更好的解决方案。 还是？

When designing a real world application that is expected to handle 10⁶ entities at a go, you will not want to make that a synchronous operation in the first place. 10⁶ entities, each with possibly its own database lookups and inter-service calls, are 10⁶ potential points of failures. We need to ensure that throttling & retry mechanisms, state management and idempotency safeguards, are put in place. If your code is supposed to handle a million entries in a single-threaded synchronous call, maybe take another pass at that design.

在设计一个现实世界中的应用程序时，它希望一次处理10个实体，您将不希望首先进行同步操作。 10个实体(每个实体可能都有自己的数据库查找和服务间调用)是10个潜在故障点。 我们需要确保节流和重试机制，状态管理和幂等性保障措施到位。 如果您的代码应该在单线程同步调用中处理一百万个条目，则可以在该设计上再进行一次。

The point I am trying to make here is that scalability is for the most part a high-level architectural concern. It can be solved in multiple ways, many of which will have no bearing on the code you write. If you are having to worry about meeting your scale requirements at code method level, and for which you are having to compromise on readability, then first we should consider re-examining the architecture once.

我在这里要说明的一点是，可伸缩性在很大程度上是高层架构问题。 它可以通过多种方式解决，其中许多方式与您编写的代码无关。 如果您不得不担心在代码方法级别上满足规模要求，并且不得不在可读性上做出妥协，那么首先我们应该考虑重新检查一次体系结构。

However, say you are building a high frequency trading platform, where every nanosecond counts. Here it makes sense to opt for the first solution. But if the end customer is a human, a few seconds here or there is usually not a problem for them. However, if by sacrificing readability it takes your team several months to deliver a new feature that does not break every other thing in your codebase, or it takes you several hours more to identify and patch a severe bug, that prevents your customer from using your application, that actually affects your customer. So key take away.

但是，假设您正在构建一个高频交易平台，其中每一分之一秒都很重要。 在这里选择第一个解决方案是有意义的。 但是，如果最终客户是人类，那么在这里停留几秒钟通常对他们来说就没有问题。 但是，如果通过牺牲可读性来使您的团队花费数月的时间来提供不会破坏代码库中其他所有内容的新功能 ，或者花费大量时间来识别并修补严重的bug，则可能会阻止客户使用您的应用程序 ， 实际上会影响您的客户。 所以钥匙带走了。

Always Code as per your customer.

始终根据客户进行编码。

2.硬件成本 (2. Hardware Costs)

Also it will incur more hardware costs.

另外，它将导致更多的硬件成本。

True. But today hardware is cheap.[4]

真正。 但是今天硬件很便宜。[4]

Now I am not advocating wastefulness. Even if it's cheap, it still costs money, and it still costs the environment.

现在我不提倡浪费。 即使很便宜，它仍然要花钱，而且仍然要花费环境。

But if you were to sacrifice readability to save on hardware costs, you’ll end up, costing your team more. Because with low readability, more man hours needs to spent on bugs and on each new feature. And skilled man hours is far more expensive, both in financial and environmental terms. (I am not qualifying this statement here, because I think it a simple google search will suffice, but If you disagree, drop me a note, and we can discuss further )

但是，如果您牺牲了可读性以节省硬件成本，那么最终您将付出更多的代价。 由于可读性较低，因此需要花费更多的工时用于错误和每个新功能。 从财务和环境角度来讲，熟练工时的成本要高得多。 (我在这里没有限定此声明，因为我认为这是一个简单的Google搜索就足够了，但是如果您不同意，请给我留言，我们可以进一步讨论)

So key Takeaway.

所以关键。

Code should be as optimised as possible, as long as it does not compromise comprehension.

只要不影响理解力，代码就应尽可能优化。

测量可读性？ (Measuring Readability?)

Hmm ok I hear you ask,

嗯，好的，我听到你问了，

“Makes sense, but readability is a subjective entity. How do we measure it? To be able to enforce this in practise, I need to have some objective way of measuring it, Right? Otherwise its not that helpful”

“说得通，但可读性是一个主观实体。 我们如何测量？ 为了能够在实践中实施这一点，我需要一种客观的方法来衡量它，对吗？ 否则它没有帮助”

Well, as you mentioned, it is a subjective quality, so while we cannot get an exact measurement, we can follow the famous WTFs per minute rule [5] to get a relative measurement, which if you think about it, is all we need.

好吧，正如您提到的，这是一个主观的素质，因此尽管我们无法获得精确的度量，但我们可以遵循著名的每分钟WTF规则 [5]来获得相对度量，如果您考虑一下，这就是我们所需要的。

So a simple way to go about it is,

一个简单的解决方法是

Get your peers to read your code. The fewer number of times they get surprised while reading your code, the better the readability.

让您的同龄人阅读您的代码。 他们在阅读代码时感到惊讶的次数越少，可读性越好。

Also one cool thing to notice. The parameters of the use case we mentioned are sufficiently vague, and if you think about it, many of the products we build and use in our day to day lives will fall within that description, including Medium. — I’ll not explain further, but dwell on this for a minute. It will be worth it. :)

还有一件很酷的事情要注意。 我们提到的用例的参数很模糊，如果您考虑一下，我们在日常生活中构建和使用的许多产品都将落入该描述之内，包括Medium。 —我将不做进一步解释，但将其停留一分钟。 这将是值得的。 :)

Phew! That was a long post. However, there are a lot of nuances and questions that I have left out. So if you disagree with anything I said, or want to discuss further on any of the above, or engage further on any of the nuances I may have omitted from mentioning here, drop a note. I’ll be more than happy to engage. Debating and discussing code is one of those few pleasures of life that can and should be enjoyed in the excess.

！ 那是一个很长的帖子。 但是，我遗漏了许多细微差别和问题。 因此，如果您不同意我说的话，或者想就上述任何内容进行进一步讨论，或者想进一步谈谈我可能在此处未提及的任何细微差别，请添加注释。 我会很高兴参与。 辩论和讨论代码是可以并且应该过度享受的少数生活乐趣之一。

资料来源，脚注和更多阅读链接 (Sources, Footnotes & Further Reading Links)

• A good introduction wiki on Side-effects :

  关于副作用的良好介绍Wiki：

  [1]

  [1]

  Side effect (computer science), Wikipedia

  副作用(计算机科学) ，维基百科

• An insightful question that highlights the often unintentional consequences of side-effects in code :

  一个有洞察力的问题，突出了代码中副作用经常造成的意外后果：

  [2]

  [2]

  Does System.out.println() have a side effect in Java? (2016), Stack Overflow

  System.out.println()在Java中是否有副作用？ (2016)，堆栈溢出

• A cool page, that collates a vast selection of Murphy’s laws. Take a Look. The Laws are fun, depressing, inspiring, outlandish and relatable all at the same time :

  很棒的页面，汇集了墨菲定律的各种选择。 看一看。 这些法律既有趣又令人沮丧，鼓舞人心，古怪而又相关：

  [3]

  [3]

  Murphy’s Law | Really Cheap Thoughts

  墨菲定律| 真正便宜的想法

• A good introduction article for Hardware vs Software Solutions to a problem. Slightly dated, but gets you thinking about the next right questions to ask :

  关于硬件与软件解决方案的一个很好的介绍文章。 有点过时了，但是让您思考接下来要问的正确问题：

  [4] J. Atwood,

  [4] J. Atwood，

  Hardware is Cheap, Programmers are Expensive (2008), CODING HORROR

  硬件便宜，程序员昂贵 (2008年)，编码恐怖

• A Blog that goes into some details on the WTFs per minute rule:

  一个博客，详细介绍了每分钟WTF规则：

  [5] A. Eaton,

  [5] A. Eaton，

  WTF Per Minute — An Actual Measurement for Code Quality (2016), Blogspot

  每分钟WTF —代码质量的实际衡量标准 (2016)，Blogspot

• My opinions on what constitutes good coding are heavily influenced by the works of Mr. Robert C. Martin.

  罗伯特·C·马丁先生的作品对我认为好的编码有很大影响。

  [5]

  [5]

  Amazon Link For his book Clean Code.

  Amazon Link对于他的书Clean Code。

最后一道外卖 (One Last Takeaway)

Before you go, here is one last takeaway. If you often review code for codebases that meet the above use-case, and don’t want to, have to, explain to the author at length what you expect to see in their code. Simply, send them a screenshot of this powerful and succinct (and heavily paraphrased) quote by Frank Underwood.

在您出发之前，这是最后一个要点。 如果您经常查看满足上述用例的代码库代码，而又不想向作者详细解释您希望在其代码中看到的内容。 简单地，给他们发送一张截图，上面是弗兰克·安德伍德(Frank Underwood)引述的这个有力而简洁的(且意味深长的)表述。