用什么代碼可以改變鍵盤

by John Cobb

約翰·科布(John Cobb)

為什么我改變了對代碼質量的看法 (Why I changed the way I think about Code Quality)

What do you think about when you think about code quality?

當您考慮代碼質量時，您會怎么看？

Is it consistency? Enforcing a set of standards and best practices on your code through linter rules and formatters? How about ensuring your code has tests that run automatically during your build process? What about pull requests and code reviews — protecting your master branch from direct commits and having peers review your code?

是否一致？通過linter規則和格式化程序對代碼執行一套標準和最佳實踐？如何確保您的代碼具有在構建過程中自動運行的測試？拉取請求和代碼審查又如何—保護您的master分支免受直接提交并讓同級審查您的代碼？

They’re some of the things that come to mind for me. Automated processes and manual checks. Smart and efficient. Yet, while they’re all useful, they really only address half of the problem.

這些是我想到的一些東西。自動化流程和手動檢查。聰明高效。然而，盡管它們都很有用，但實際上只能解決一半的問題。

我們不能使一切自動化 (We can’t automate everything)

Automation is crucial for maintaining code quality. Static analysis of your syntax with a linter and automated testing should be mandatory. But I can write code that passes all the automated processes without any guarantee to its actual quality.

自動化對于保持代碼質量至關重要。必須使用lint對語法進行靜態分析并進行自動測試。但是我可以編寫通過所有自動化過程的代碼，而不能保證其實際質量。

Does the code follow established patterns? Does it use existing modules, or does it duplicate code? Is everything named sensibly? Is the code in the right place in the codebase? Will this change have wider, unintended, implications? Does this code actually address/solve what it intends to? Does it even work?

代碼是否遵循既定模式？它使用現有模塊還是重復代碼？一切都被合理地命名了嗎？代碼是否在代碼庫中的正確位置？這種變化會產生更廣泛的，意想不到的影響嗎？此代碼是否實際解決/解決了預期的問題？它甚至工作？

Automated processes can’t answer those questions for you (yet). If you (or another human being) aren’t asking these questions of your code, then you’re probably not shipping quality code. That’s why we have code reviews.

自動化流程無法為您回答這些問題(至今)。如果您(或其他人)沒有問代碼的這些問題，那么您可能沒有在交付質量代碼。這就是為什么我們要進行代碼審查。

良好的代碼審查不僅僅應包含代碼 (A good code review should be about more than the code)

Of course a code review should be about the code (it’s right there in the name after all). But it should also be about the broader questions posed above, and also about the end product.

當然，代碼審查應該是關于代碼的(畢竟它就在名稱中)。但這還應與上面提出的更廣泛的問題以及最終產品有關。

I’ve noticed a tendency for developers to treat code reviews as perfunctory. A rudimentary check of the modified code. A comment on any obvious mistakes (or just picking a nit or two to look busy).

我注意到開發人員傾向于將代碼審查視作敷衍。對修改后的代碼的初步檢查。對任何明顯的錯誤發表評論(或者只是挑一兩個尼特，讓他們看起來很忙)。

Five minutes, job done. Looks good to me.

五分鐘，工作完成。 對我來說看起來不錯 。

But, code that doesn’t address the requirements of the task is not quality code. Code that produces console errors or visual bugs in the device/browser is not quality code. Neither of those things can be picked up in a perfunctory code review. You can’t adequately review code unless you actually run it.

但是，不能滿足任務要求的代碼不是質量代碼。在設備/瀏覽器中產生控制臺錯誤或視覺錯誤的代碼不是質量代碼。這些功能都無法在敷??衍的代碼審查中找到。除非您實際運行代碼，否則您將無法充分審查代碼。

I propose that a good code review should involve at minimum:

我建議良好的代碼審查至少應涉及：

Pulling down the branch to a local environment.
將分支拉到本地環境。
Building the project (and checking that the linter and tests all pass).
構建項目(并檢查短毛絨和測試是否全部通過)。
Checking that the code runs error free in the target browsers/devices.
檢查代碼是否在目標瀏覽器/設備中無錯誤運行。
Checking that the completed work matches the requirements of the task.
檢查完成的工作是否符合任務要求。

If there are any issues with any of those steps the pull request should be rejected. Do not pass Go. Do not collect $200. Do not merge to master.

如果這些步驟中的任何步驟有任何問題，則應拒絕請求請求。不要通過圍棋。不要收取200美元。不要合并到母版。

Reviewers should also use the code review as an opportunity to ask questions. If you don’t understand the code, then you shouldn’t approve the pull request. Don’t assume that the author knows more than you do — if it doesn’t make sense to you, ask for clarification.

審閱者還應將代碼審閱作為提問的機會。如果您不理解代碼，則不應批準請求請求。不要以為作者比你了解更多—如果這對你沒有意義，請澄清。

The reviewer has equal responsibility with the author for the quality of the code. This is a mindset that is essential for maintaining code quality.

審閱者與作者對代碼質量負有同等責任。這是保持代碼質量必不可少的一種心態。

Comprehensive code reviews go a long way to helping ensure code quality. But there are steps you can take before you even open a pull request. Small things you can do that will help enhance the quality of your code, and reduce the effort required to review it.

全面的代碼審查對確保代碼質量大有幫助。但是，您甚至可以在打開拉取請求之前執行一些步驟。您可以做的小事情將有助于提高代碼的質量，并減少檢查代碼所需的工作。

仔細檢查您自己的作品是否完整 (Double check your own work for completeness)

I have an annoying habit. When I finish writing the last lines of code for a task, I mentally check the task off as complete.

我有個煩人的習慣。當我完成任務的最后幾行代碼編寫時，我會在腦海中檢查任務是否完成。

If I were to listen to that impatient voice in my head, I’d submit my pull request right then. But that code would likely contain many, or all, of the following:

如果我想聽聽我腦子里那急躁的聲音，那我馬上就要提交我的請求。但是該代碼可能包含許多或全部以下內容：

Missed requirements.
錯過的要求。
Missing test cases.
缺少測試用例。
Superfluous, unused or draft code.
多余的，未使用的或草稿的代碼。
Not enough code comments.
代碼注釋不足。
Visual bugs in some browsers/devices.
某些瀏覽器/設備中的視覺錯誤。

If any of those things are true about your code, then your code is not complete. If any of those things end up in the master branch, then you have degraded the quality of the codebase.

如果您的代碼中有任何上述情況，則您的代碼不完整。如果這些事情中的任何一個最終出現在master分支中，則說明代碼庫的質量下降了。

The main point here is this: code quality starts with the code author. You shouldn’t rely on automated tasks, a code review, quality assurance or user acceptance testing to catch your mistakes.

這里的重點是：代碼質量始于代碼作者。您不應該依靠自動化任務，代碼審查，質量保證或用戶驗收測試來發現錯誤。

Double checking work for completeness is an essential first step toward code quality. It’s the easiest step to take, but also the easiest one to ignore.

進行雙重檢查以確保完整性是邁向代碼質量必不可少的第一步。這是最簡單的步驟，也是最容易忽略的步驟。

You should only open up a pull request when you are certain your code is complete.

僅在確定代碼完成后才應打開拉取請求。

對分支機構進行自我審查 (Perform a self review of your branch)

I’m always surprised at how many issues — or opportunities to refine a solution — I can find in my own code. Issues and opportunities that only become visible to me when I step back and view my changes in isolation.

我總是在自己的代碼中發現有多少問題或改進解決方案的機會，總是感到驚訝。當我退后一步，孤立地查看我的更改時，問題和機會才對我可見。

You can review your work and apply your own feedback before assigning a team member to review your work. You can also use this opportunity to leave comments on the pull request to clarify anything for the reviewer.

您可以在分配團隊成員來審查您的工作之前，先審查您的工作并應用您自己的反饋。您還可以利用此機會在請求請求中留下評論，以使審閱者澄清任何事情。

Taking time to ensure your work is complete, to correct obvious mistakes, or assess your solution, will enhance the quality of your code. It also reduces the effort required to review it.

花一些時間來確保您的工作完成，糾正明顯的錯誤或評估您的解決方案，將會提高代碼的質量。它還減少了審核所需的工作。

It might also save you some embarrassment. I know it has for me.

這也可能使您免于尷尬。我知道它適合我。

確保代碼質量應該是每個開發任務的內在要求 (Ensuring code quality should be an inherent requirement of every development task)

You may be thinking that this approach adds time to the length of a task. And you’re right, it does. But that isn’t a bad thing.

您可能會認為這種方法會增加任務時間。你是對的，的確如此。但這不是一件壞事。

Efficiency is important, but laziness and apathy is harmful. Apathy leads to a bloated, inconsistent code base. Laziness creates a growing backlog of bad technical debt. We can’t be passive and maintain code quality. It requires time and effort.

效率固然重要，但懶惰和冷漠是有害的。冷漠會導致a腫的，不一致的代碼庫。懶惰導致不良技術債務積壓的情況越來越多。我們不能被動地保持代碼質量。這需要時間和精力。

Changing the culture around code quality can be hard. Project managers and product owners generally aren’t concerned about code quality — they have their own concerns. Requesting extra time for code quality processes can sometime fall on deaf ears. However, maintaining code quality shouldn’t be thought of as something extra — it should be an inherent requirement of every task.

改變圍繞代碼質量的文化可能很難。項目經理和產品所有者通常不關心代碼質量-他們有自己的問題。為代碼質量過程請求額外的時間有時會置若de聞。但是，不應將保持代碼質量視為額外的工作—它應該是每個任務的固有要求。

As developers, if we don’t change the way we think about code quality, we can’t expect anyone else to.

作為開發人員，如果我們不改變我們對代碼質量的方式，我們不能指望別人。

Nothing I’ve talked about here is particularly groundbreaking, nor is it prescriptive. Not every team, workplace, or project is the same, and some of the above may not be applicable to you.

我在這里談論的沒有什么特別開創性的，也不是規定性的。并非每個團隊，工作場所或項目都是相同的，并且上述某些內容可能不適用于您。

I do believe there is often a gap between the way developers think about code quality, and the actual actions taken to address it. If you’ve found that too, then hopefully there is something you can take away from this article — or perhaps you’ve already taken a different approach to addressing it. I’d love to hear your suggestions in the comments.

我確實相信開發人員對代碼質量的思考方式與為解決該問題而采取的實際措施之間通常存在差距。如果您也發現了這一點，那么希望本文可以對您有所幫助–也許您已經采用了另一種方法來解決它。我很想聽聽您在評論中的建議。

Thanks for reading!

謝謝閱讀！