如何制定可執行的代碼規範？

接收程序員的技術早餐

作者｜erichua23

編輯｜小智

制定代碼規範並不難，但你知道如何讓它可執行嗎？

寫在前面

回想起來自己工作這麼些年，也經歷了不少團隊，經歷的項目更不算少了， 但是要說到代碼規範， 問我我經歷的這些代碼規範是不是滿意，我不得不如實回答：不是很滿意。當然我自己的代碼規範和風格也沒有完全固化下來，近一年左右也開始關注到這個問題，為了讓自己的代碼風格能逐漸固化，我會專門用一個筆記來記錄一些可能自己會糾結的寫法，這樣做了以後明顯能感覺到自己代碼風格的飄忽程度有所收斂。恰巧公司負責的項目也需要整理代碼規範，正因如此我開始思考如何制定可執行的代碼規範這個問題。

提到團隊的代碼規範，不止我經歷過的，我和一些朋友也有聊過， 有微軟那個級別的，也有 BAT 這種級別的，項目大的也有，小的亦很多。其中不乏規範的做的比較好的，有規範、有工具、還會有 Code Review 來保證。但是大公司規範和流程真的適合所有團隊嗎？我所看到的是大部分團隊參照某某公司的規範和流程，定義了一個非常嚴格的標準，然而實際上並沒有嚴格實施下去或者沒有持續實施下去。最後都會甩鍋給「歷史包袱太重」、「開發人員太多太雜難以推廣」這樣的理由。

近半年到一年在代碼規範這一塊我主要思考如何在中小團隊沒有代碼規範的基礎上制定代碼規範。根據自己的思考也正在組內逐步實踐，從目前實踐情況來看我是比較滿意的，所以把自己觀點寫出來，希望能對跟我有同樣困惑的人有些幫助。

代碼規範不應該被定為 KPI

所有的規範，包括但不限於代碼規範，都會包含規範制定、規範推廣執行、規範修正的過程。 其中規範的推廣和執行通常是最難的（這就是為什麼有很多流程文檔，但是流程還是非常混亂的原因），而制定了什麼樣的規範直接決定了推廣執行的難度，所以我們先從代碼規範的制定說起。

大部分團隊應該都是有 KPI 的，而且一般重要的事情都會被定成 KPI， 所以有些團隊為了強調代碼規範， 將其定為某些員工的 KPI，這樣重視代碼規範行為我是非常欣賞的，但是我不認同，因為我認為代碼規範不應該是一個文檔， 代碼規範應該是一種行為， 一種持續的行為，而 KPI 是要求可以量化有明確目標的。若把代碼規範當作 KPI， 背了 KPI 的員工為了讓 KPI 可量化， 通常情況會寫出來一個代碼規範文檔，眾所周知文檔最可 量化的當然是頁數，故最終可能會產出一個幾十頁的代碼規範，它可能是結合了 Google、Facebook、Tencent 等等大公司的代碼規範，幾乎面面俱到，看起來就很高大上。

代碼規範文檔出來了，KPI 看起來也完成得不錯，那然後呢？如果我們把代碼規範理解為一種行為，那這文檔就僅僅只是一個行為準則，它就像是一部法律，要求大家都要如何做，所以接下來更重點的工作應該是去讓這些文檔落地，讓大家理解認可執行它。並且還需要有相應的監督機制、審查機制來保證大家確實按規範在寫代碼。但是後面這些，也就是整個代碼規範實施最難的點，要量化又極其不易。能如何量化呢？量化推廣程度？量化大家對各條代碼規範的理解透徹程度？難道用考試來量化嗎？這就是把代碼規範設定成 KPI 的尷尬， 為了讓 KPI 看起來豐滿， 產出了一個豐滿的規範， 而對於整個過程中最難的落地執行環節， 豐滿的規範為其增加了阻力。

以前我對於代碼規範的理解是也是越豐富越好，但是在近半年推廣代碼規範的過程中我開始青睞簡單一些的代碼規範，因為我相信大部分人會贊同：一個被 100% 徹底執行了的 40 分代碼規範應該是好於一個被執行了 40% 的 100 分代碼規範。

制定代碼規範要循序漸進

這個觀點可能會更比較多人的看法不太一樣， 因為很多人都認為規範應該前期就定下來，而且儘可能面面俱到，否則後面定規範容易背上歷史包袱。前期就應該定規範的這個觀點我比較認同，首先我們拋開你們團隊已經有非常完善代碼規範這種情況，因為如果是那樣，你只需要按原有規範執行即可。

這裡主要討論新項目沒有規範的情況下怎麼做，我們可以復盤一下新項目開始階段，通常情況新項目需求節奏都會非常快，基礎框架、基礎組件、大批量業務需求要開發，又因為是新項目，通常不會有特別多的人力投入，這種情況下，一個很嚴格冗長的代碼規範，要求大家在拚命跑的過程中還要去理解執行你的規範，可能性大嗎？所以這個時期的代碼規範需要非常簡單易於理解，要在所有人即使在趕需求，也能忍受的範圍內製定規範。這個階段最急迫的需求是用簡單的代碼規範讓大家養成習慣，提升意識，宣告這個項目是有規範的。

我們拿前端項目來舉例，首先應該先保證 JS 代碼風格是對的，其次可能根據技術選型不同（例如 Angular，React），要遵循另外一批 Best Practice。按上述思路，我會在前期只要求大家 JS 代碼格式規範就行了。因為把各種 Best Practice 一股腦的全丟進去容易繞暈大家。 如果你真的捨不得那些 Best Practice，我建議將其列為建議級別的，先不做必須，必須的條目儘可能精簡。

制定代碼規範需要"獨裁"

上面一段提到代碼規範應該循序漸進，但是簡單的規範從何而來呢？之前看到過的一種做法是：團隊內大家一起討論，民主決定某一些規範的細節，因為這樣可以出來一個適配這個團隊的代碼規範。

這聽起來很美好，非常民主，大家很平等，但是回想一下以前這麼做的結果是什麼？我猜應該會有很多人又回憶起「大括弧應不應該換行」、「else 是否應該換行」、「是否允許空兩行」、「JS 結尾帶不帶分號」等等類似的爭論吧，然而這些爭論是有必要的嗎？說白了，大部分爭論找的理由都只是在為自己的代碼習慣爭取更多空間。這樣的爭論還只是「民主」引發問題的開始，更嚴重的是這會在所有開發人員心中形成一種「規範是可以商量和討論的」心理暗示，這必對後續規範的執行成為阻礙，特別是一些本身就有爭議的點，總會有人伺機反撲。

另外，「民主」的規範其實很難做到讓所有人心理上平衡，例如可能會讓 B 開發覺得自己在遵從 A 開發的習慣，即使這種感覺可能不是那麼強烈，它也會變成規範執行的阻力。

正因為上述原因，我非常建議制定規範時「獨裁」。我們的目標很清晰，就是要求代碼寫法一致，「獨裁」的基礎上可以選擇一個第三方的標準，例如細的條目可以完全選擇 Google 或者 Facebook 或者其他一些大公司的標準（當然可能還需要考慮我上面提到的循序漸進，做裁剪，但是規則細則不要再去討論和挑戰）。首先可以保證的是這些規範不會有太大的問題，跟著做不會犯大錯；其次，「獨裁」使用的規範來源於第三方，對團隊內所有人公平；最後，這樣的規範和行業更親近。

我在我們的前端項目裡面就選擇了 StandardJS 的規範，StandardJS 的出現初衷也正是為了解決上述「民主」引發的問題。除此之外，還有一個好處是這些第三方規範的成熟不只是規範本身，它的配套工具會成熟很多，可以節省自己很多成本。

代碼規範從「立法」到「執法」

上面我們已經討論了如何建立代碼規範，主要強調了代碼規範不應只是一紙空文、代碼規範要循序漸進、代碼規範的制定需要「獨裁」。這些都屬於「立法」過程，接下來要討論的必然是「執法」，代碼規範的「執法」主要需要關注兩點，一點是「違法」行為的判定，另一點是「違法」行為的責任追究，也就是代碼規則檢查以及發現不符合規範的代碼應該由誰來負責。

代碼規則檢查通常直接使用現有成熟工具就好，例如前端開發常用的 ESLint，現在各種語言都有各自比較成熟的工具，我這裡想強調的是幾個檢查代碼的時機，一是寫代碼的時候，這是源頭，配置一個好的 IDE 檢查規則能從源頭避免不規範的代碼。二是提交時候，通常是設置 git/svn 的 hooks（PS: git 的 hooks 在 2.9.0 之前相當的難用，如果你用的版本低於 2.9.0，可以考慮升級並配置代碼檢查的鉤子）。三是 CI 的時候，這是最後一關，可以保證合流以後的代碼不出現規範的問題。只要在上面三個點嚴格執行了，不規範的代碼幾乎已經無處可藏。

「違法」行為判定儘可能通過工具來判定，那如果出現了庫裡面提交了不合規則的代碼應該由誰去改呢？如果有 CI，那隻需要增加提交構建，即可在 push 後的第一時間揪出違規者。如果沒有 CI，我建議是先建立 CI，如果實在沒有，那可以考慮最後提交代碼負責制，最後提交代碼的人可以去找這份代碼是 merge 了誰的，追溯到上游把「鍋」丟出去，最終找到違規者並要求改進（不限於代碼的改進，更重要的是各種代碼檢查環境的配置）。這樣的定義可以讓所有開發知道遇到問題以後該如何走下一步，我認為是非常有必要的。

說到這裡我猜必然有讀者想到了 Code Review，實際上 Code Review 不應該是去關注代碼風格的，所有到 Code Review 環節的代碼必然是要過了代碼風格檢查的，Code Review 主要關注的是代碼結構設計和代碼邏輯，它是在代碼規範上一層的東西。如果你的團隊在使用 Code Review 來保證代碼規範，那你們可能需要進一步完善自己的代碼規範檢查工具。

總結思考

代碼規範的好處大家都知道，但是任重道遠。真正去推行代碼規範的人，如果按我上面說的幾點去做，可能會有各方面的壓力，特別是上面提到的「獨裁」和「執法」兩點，但是從我自己的實踐經驗來看，想像中的壓力小於實際，主要還是需要向同事們解釋清楚各種做法的理由，得到理解和支持。為了避免前期的推行的壓力過大，可以考慮裁剪規則（特別是在沒有很好代碼規範文化的團隊內），因為提升團隊人員意識和養成代碼規範的習慣應該是最最首要的任務，這兩點有了以後，再逐步的把要求提高，應該會容易得多。這個過程有困難，但是我堅定的認為這是值得的。

今日薦文

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！