摘要：?Any fool can write code that a computer can understand. Good programmers write code that humans can understand. 普通的工程師堆砌代碼，優(yōu)秀的工程師優(yōu)雅代碼，卓越的工程師簡化代碼。

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

普通的工程師堆砌代碼，優(yōu)秀的工程師優(yōu)雅代碼，卓越的工程師簡化代碼。如何寫出優(yōu)雅整潔易懂的代碼是一門學問，也是軟件工程實踐里重要的一環(huán)。筆者推薦三本經典的書籍《代碼整潔之道?》、《編寫可讀代碼的藝術》、《重構:改善既有代碼的設計》，下文重點將從注釋、命名、方法、異常、單元測試等多個方面總結了一些代碼整潔最佳實踐，大部分是筆者總結于以上三本書中的精華，也有部分是筆者工程實踐的總結。篇幅有限，本文將總結性給出一些實踐建議，后續(xù)會有文章來給出一些代碼整潔之道的事例。

注釋

• 不要給不好的名字加注釋，一個好的名字比好的注釋更重要
• 不要“拐杖注釋”，好代碼 > 壞代碼 + 好注釋
• 在文件/類級別使用全局注釋來解釋所有部分如何工作
• 一定要給常量加注釋

• 團隊統(tǒng)一定義標記

  • TODO? 待處理的問題
  • FIXME? 已知有問題的代碼
  • HACK 不得不采用的粗糙的解決方案
• 在注釋中用精心挑選的輸入輸出例子進行說明
• 注釋應該聲明代碼的高層次意圖，而非明顯的細節(jié)
• 不要在代碼中加入代碼的著作信息，git可以干的事情不要交給代碼
• 源代碼中的html注釋是一種厭物, 增加閱讀難度
• 注釋一定要描述離它最近的代碼
• 注釋一定要與代碼對應
• 公共api需要添加注釋，其它代碼謹慎使用注釋

• 典型的爛注釋

  • 不恰當?shù)男畔?/li>
  • 廢棄的注釋
  • 冗余注釋
  • 糟糕的注釋
  • 注釋掉的代碼

• 唯一真正好的注釋是你想辦法不去寫的注釋

  • 不要有循規(guī)式注釋，比如setter/getter注釋
  • 不要添加日志式注釋，比如修改時間等信息（git可以做的事情）
  • 注釋一定是表達代碼之外的東西，代碼可以包含的內容，注釋中一定不要出現(xiàn)
  • 如果有必要注釋，請注釋意圖（why），而不要去注釋實現(xiàn)（how)，大家都會看代碼
  • 適當添加警示注釋

命名

• 盡可能使用標準命名方法，比如設計模式，通用學術名詞等

• 命名要找更有表現(xiàn)力的詞

  • 使用更專業(yè)的詞，比如不用get而使用fetch或者download
  • 避免空泛的名字，像tmp
  • 使用具體的名字來細致的描述事物
  • 給變量名帶上重要的細節(jié)，比如加上單位ms等
  • 為作用域大的名字采用更長的名字，作用域小的使用短名字
  • 變量類型為布爾值表達加上is，has，can，should這樣的詞會更明確
• 變量名稱長短應該與其作用域對應
• 別害怕長名稱，長而具有描述性的名稱比短而令人費解的名稱好
• 函數(shù)名稱應該說明副作用，名稱應該表達函數(shù)，變量或類的一切信息，請不要掩蓋副作用，比如CreateAndReturnXXX

方法

• 函數(shù)不應該有100行那么長，20行封頂最好

  • if else while等控制語句其中代碼塊應該只有一行，也就是一個函數(shù)調用語句
  • 函數(shù)的鎖進層次不應該多于兩層
  • 一個函數(shù)只做一件事，一個函數(shù)不應該能抽象出另外一個函數(shù)
• 某個公共函數(shù)調用的私有函數(shù)緊隨其后

• 最理想的參數(shù)是零參數(shù)，最長不要超過三個入參，盡量不要輸出參數(shù)

  • 如果函數(shù)傳入三個及以上參數(shù)最好將其抽象為類
  • 標識參數(shù)十分丑陋，向函數(shù)傳入布爾值用于區(qū)分不同業(yè)務的做法很丑陋，應該拆分為多個函數(shù)
• 別返回null值，拋出異常或者返回特殊對象，盡量避免NPE
• 別傳入null值

異常與錯誤

• 抽離try catch包含的代碼塊，其中代碼塊抽象為一個函數(shù)
• 拋出的每個異常，都應當提供足夠的環(huán)境說明，已便判斷錯誤的來源與處所
• 不要將系統(tǒng)錯誤歸咎于偶然事件

并發(fā)

• 分離并發(fā)相關代碼與其它代碼
• 嚴格限制對可能被共享的數(shù)據(jù)的訪問
• 避免使用一個共享對象的多個同步方法
• 保持同步區(qū)域微小，盡可能少設計臨界區(qū)

單元測試

• 不要怕單元測試的方法名字太長或者繁瑣，測試函數(shù)的名稱就像注釋
• 不要追求太高的測試覆蓋率，測試代碼前面90%通常比后面10%花的時間少
• 使用最簡單的并且能夠完整運用代碼的測試輸入
• 給測試函數(shù)取一個完整性的描述性名字，比如? Test _
• 測試代碼與生產代碼一樣重要
• 如果測試代碼不能保證整潔，你就會很快失去他們
• 每個測試一個斷言，單個測試中斷言數(shù)量應該最小化也就是一個斷言

• FIRST原則

  • 快速 Fast
  • 獨立 Independent? 測試應該相互獨立
  • 可重復 Repeatable? 測試應當在任何環(huán)境中重復通過
  • 自足驗證 Self-Validating ? 測試應該有布爾值輸出
  • 及時? Timely ? 最好的方式是TDD

代碼結構

• 代碼行長度控制在100-120個字符
• 可能用大多數(shù)為200行，最長500行的單個文件構造出色的系統(tǒng)

• 關系密切的代碼應該相互靠近

  • 變量聲明應該靠近其使用位置
  • 若某個函數(shù)調用了另外一個，應該把他們放在一起，而且調用者應該放在被調用者上面
  • 自上向下展示函數(shù)調用依賴順序
• 應該把解釋條件意圖的函數(shù)抽離出來，盡可能將條件表達為肯定形式
• 不要繼承常量，比如接口中定義常量，不要使用繼承欺騙編程語言的作用范圍規(guī)則
• 模塊不應了解它所操作對象的內部情況
• DTO（Data Transfer Objects）是一個只有公共變量沒有函數(shù)的類
• 對象暴露行為，隱藏數(shù)據(jù)
• 不要使用“尤達表示法” 如 if(null == obj)，現(xiàn)代編譯器對if(obj = null)這樣的代碼會給出警告
• 一般情況使用if else，簡單語句使用三目運算符
• 通常來講提早返回可以減少嵌套并讓代碼整潔

設計

• 類應該足夠短小

  • 類應該滿足單一權責原則（SRP），類和模塊只有一個修改理由
  • 類應該只有少量的實體變量
  • 類應該遵循依賴倒置原則 DIP（Dependency Inversion Principle），類應該依賴于抽象而不是依賴于具體細節(jié)
  • 類中的方法越少越好，函數(shù)知道的變量越少越好，類擁有的實體變量越少越好

• 通過減少變量的數(shù)量和讓他們盡量“輕量級”來讓代碼更有可讀性

  • 減少變量
  • 縮小變量的作用域
  • 只寫一次的變量更好，如常量

• 最好讀的代碼就是沒有代碼

  • 從項目中消除不必要的功能，不要過度設計
  • 從新考慮需求，解決版本最簡單的問題，只要能完成工作就行
  • 經常性地通讀標準庫的整個API，保持對他們的熟悉程度

• 簡單設計

  • 運行所有測試
  • 不可重復
  • 表達了程序員的意圖
  • 盡可能減少類和方法的數(shù)量
  • 以上規(guī)則按重要程度排列
• 無論是設計系統(tǒng)或者單獨模塊，別忘了使用大概可工作的最簡單方案
• 整潔的代碼只提供一種而非多種做一件事的途徑，他只有盡量少的依賴。明確定義并提供盡量少的API
• 減少重復代碼，提高表達力，提早構建，簡單抽象

小結

作為代碼整潔之道系列的第一篇，本文從注釋、命名、方法，單元測試，并發(fā)等視角簡單給出了一些最佳實踐，下文我們會展開來從每個方面介紹更多的實踐事例。相信每一個優(yōu)秀的工程師都有一顆追求卓越代碼的心，在代碼整潔工程實踐上你有哪些好的建議？數(shù)百人協(xié)作開發(fā)的代碼如何保證代碼整潔一致性？歡迎大家來討論。

原文鏈接

本文為云棲社區(qū)原創(chuàng)內容，未經允許不得轉載。

創(chuàng)作挑戰(zhàn)賽新人創(chuàng)作獎勵來咯，堅持創(chuàng)作打卡瓜分現(xiàn)金大獎

總結

以上是生活随笔為你收集整理的聊聊代码整洁之道的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。