【譯】Good code Vs Bad code

• 原文地址: Good code Vs Bad code
• 原文做者: Navdeep Singh
• 譯者: Chris xiong

在寫任何一門語言的時候，它們都有好的代碼實踐和很差的代碼實踐。這兩種代碼可能都能編譯運行。可是很差的代碼可能會在開發，調試和修改中引發一些問題。在工做團隊中，不管你的程序運行情況如何，某些人總要閱讀而且修改你代碼的某些地方。他們可能會添加一些新屬性，修改一些bug,或者只是想明白它們是如何工做的。一樣的，你也會須要去讀其餘人的代碼作一樣的事情。若是代碼可讀而且容易理解，每一個人都會更舒服一些。

高質量代碼的重要性:要明白高質量代碼的重要性，首先咱們要去明白低質量的代碼可能會致使什麼問題：編寫的代碼可能會致使財務損失或者在進一步維護，改進或調整軟件時浪費更多的時間。
你可能會在某個時間寫了你的代碼，而後在很長時間後再來維護它。所以給你的程序寫文檔和命名約定都變得很是重要。
不少時候，我會聽到個人同事開玩笑說他們怎麼不記得他們幾天前剛寫的代碼或邏輯。當你把代碼寫成很差的風格後，你就會花更多的時間來回憶你到底作了什麼？當一個藝術家不瞭解它們的做品時，事情就會開始變得失控。
當寫代碼時腦海中必定要記住的幾件事情
代碼註釋:大多數現代語言都有聲明式的文檔註釋，用單行和多行註釋結合來使得代碼更易懂和維護。好的代碼註釋應該是解釋爲何這些事情要被作而不是告訴別人作了什麼事情。代碼自己應該要能告訴別人作了什麼。對註釋的須要應該是最小的。

縮進：好的代碼結構如圖所示（標準4個空格縮進），對於嘗試明白這些代碼的人來講，能明顯看到哪塊代碼開始，哪塊代碼結束，能讓他們更加清楚直接的跟隨代碼的邏輯。

Readme:當你面前有一個項目代碼，可是你設置而且第一次運行要花費你幾個小時才能對這個項目明白個大體，這是很是煩人的。若是這裏有個readme文檔，這就顯得頗有幫助了。在訪問代碼以前，先對項目進行一個簡短的介紹老是比較好的，一個正確結構化的Readme就是這樣作的。一個結構化的Readme文檔就像這樣

項目名(Project Title)

這裏寫一段項目描述

開始項目(Getting Started)

這些說明將爲您提供在本地機器上運行的項目副本，以用於開發和測試，有關如何在實時系統上部署項目的說明，請參閱部署。

先決條件(Prerequisites)

爲了安裝這個軟件你須要去作什麼事情，而且怎麼安裝

給一個例子

安裝(installing)

一步步告訴你怎麼獲得一個運行開發環境

步驟以下：

給例子

而且重複

直到結束

以一個從系統中獲取一些數據或使用它進行一些演示的小例子結束。

進行測試（running test)

如何對這個項目進行自動測試

分解成端對端測試

解釋一下這些測試都是什麼而且爲何這麼測試

give an exmaple

代碼分割測試

解釋一下這些測試都是什麼而且爲何這麼測試

give an exmaple

部署 Deployment

關於如何在實時系統上部署的一些其餘說明

構建 Build

• xxx -使用的web框架
• xxx -依賴管理
• xxx -用來生成rss源

貢獻 Contributing

請參閱CONTRIBUTING.md，瞭解咱們的行爲準則以及向咱們提交請求（PR）的過程。

版本 Version

咱們使用SemVer進行版本控制。 有關可用的版本，請參閱此存儲庫上的標籤。

做者 Authors

• chris xiong - 初始化工做

另見參與此項目的貢獻者名單。

許可證 License

該項目根據MIT許可證得到許可 - 有關詳細信息，請參閱LICENSE.md文件

告知 Acknowledgments

• 給任何使用代碼的人一些提示
• 靈感
• 等等

規範化命名:咱們常常會碰到命名爲apiManager的類。當咱們看到這種類名的時候，實際上咱們是不清楚這個類的實際用途的。根據最佳編碼實踐規範，咱們的類應該遵循單一功能原則，恰當的規範化命名結合單一功能原則可讓咱們在跟蹤一個項目時變得容易。若是類正在執行一些密集的工做單元，以便經過查看代碼塊來區分變量的什麼時候何地超出做用域，則不一樣做用域的命名規範也會有所不一樣。
避免魔法數字:一個徹底未被聲明的常量，這個值是程序能正常工做的特定值。沒有其餘人能知道爲何選擇這個數字，它最神奇的地方時，沒有人真正知道這個魔法數字是怎麼樣影響程序運行的。
魔法數字是邪惡的，咱們不該該使用它。

調整項目時間：上面的圖片說明了問題。

爲了編寫質量代碼（整潔的代碼），應該使用的一些常見作法及其相對重要性以下圖

寫高質量的代碼是一個浩大的過程。當你嘗試去寫高質量代碼時,一些須要去考慮的點以下：

• 好的代碼是組織良好的。類中的數據和函數是合在一塊兒的，類之間沒有一些無關的依賴關係。它看起來不像是「意大利麪」
• 好的代碼是很好測試的。測試用做代碼的可執行規範和其使用示例。
• 好的代碼不須要過多奇淫技巧。它以簡單明瞭的方式作事情。
• 好的代碼是以小塊，易於閱讀的小單元進行開發的。這些單元在代碼開發過程當中可以被複用。

感謝閱讀，若是你認爲它是有用的請分享:）