編碼最佳實踐 (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(n2). 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(n2) 。 加油站的數量為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)引述的這個有力而簡潔的(且意味深長的)表述。