軟件開發命名指南

摘譯自 Effectively Naming Software Thingies (by Sagi Rabinovich@Medium)

代碼是寫給人看的，好的命名對提升代碼的可讀性相當重要。

命名是一門藝術，須要有良好的描述技巧，有些人天生具有這種能力，而大多數人須要爲之奮鬥。

使用有意義的名字

• 選擇可以揭示意圖的名字。例如，定義一個變量用來表示「上次更新的記錄」，應當將它命名爲 lastUpdatedRecord，而不是 record 或 lastRecord（某個文件中的最後一條記錄？？）。

• 作有意義的區分。不要經過故意的拼寫錯誤、數字後綴或噪音詞後綴來區分類似的名字。例如，ProductData vs ProductInfo，ProductInfo 包含了什麼 ProductData 不包含的信息嗎？Data 和 Info 就是噪音詞，以它們爲後綴來區分不一樣的名字是沒有意義的。

• 增長有意義的上下文。變量 state 自身沒有明確的意義，可是把它放到一個意義明確的類裏面，別人很容易就能明白你的意圖。例如 address.state 或 engine.state，

  最不濟但也正確的作法，是將上下文做爲名字的前綴或後綴，例如 addressState。

  調用鏈中的每個部分都應當只增長新的上下文，這樣能夠縮短名字，同時保持其意義明確。

• 使用解決方案域中的名字。代碼會被程序員閱讀，因此能夠而且應該使用計算機科學術語、模式名、算法名、數學術語等。

• 使用問題域中的名字。若是要表達的內容與問題域聯繫更爲緊密，那麼問題域中可能有合適的名字可用。使用問題域中的名字有助於更好的瞭解問題域，與客戶擁有共同語言，而且能夠解耦問題域的概念和特定解決方案。你可使用 string address 定義一個來表達「送貨地址」的變量，可是使用 Address shippingAddress 更加明確和健壯。

  // instead of
  String state
  String streetAddress
  Int houseNumber
  
  // use
  Address address
  複製代碼

• 不要使用縮寫。使用 getWindow 而不是 getWin。

概念

命名與概念的抽象和封裝行爲有關。

• 爲每個抽象概念挑選惟一的名字 並堅持使用它。讓團隊成員在表達同一個概念時使用相同的名字。

• 不要使用 雙關語，不要爲不一樣的事物使用相同的名字。例如，有兩個類，一個類使用 add() 方法建立並添加用戶，另外一個類有一個方法用來往集合中插入一個參數，爲每個抽象概念挑選一個名字 這一原則可能會誤導你爲兩個方法取一樣的名字 add()，事實上兩個方法有不一樣的語義。

• 避免意象映射（mental mapping）。這一點很是重要。不要讓讀者將名字理解爲他們知道的其餘東西。甚至應該爲循環計數器命名，使其更容易理解。不要作一個炫耀智力的聰明程序員，要作一個清晰爲王的專業程序員。

• 爲通用操做約定統一的名字。例如，如何獲取對象的 Id ?

  worker.getId()
  candidate.id()
  employee.id.get()
  supervisor()
  複製代碼

• 使用精確的對立詞。若是你能夠 open()，你應該也能夠 close()，若是你能夠 start()，你應該也能夠 stop()。

噪音和樣板

命名應該儘量的乾淨和短小。噪音讓讀者閱讀更多的內容卻沒有產生任何好處，而是帶來困惑。

• 不要製造噪音。你的 ProductInfo 什麼意思？它與 ProductData 有何不一樣？相似這樣的後綴就是噪音。

• 避免註釋。好的命名遠勝於註釋。

• 小心 I 開頭的命名（接口陷阱）。不要經過給具體類添加一個前綴 I 的方式來得到一個接口類。IDollar 不是一個比 Currency 好的名字。Carlo Pescio 在其博文 Your coding conventions are hurting you 中詳細闡述了這一觀點。

• 不要增長沒必要要的上下文。例如，不要把項目名的縮寫做爲前綴，這會影響 IDE 的自動補全功能，而且難以在其餘項目中複用。

虛假信息

• 避免使用與要表達的含義以外的含義過於相關的詞和縮寫詞。

  避免在名字中使用數據類型，例如 accountList，或許有一天有人會將數據結構改成使用 hashSet，這個名字將失去意義，若是使用 accounts 就不會有這個問題。

• 避免在長名字中間插入有細微的差異的詞。例如，使用 o 或 l，它們與 0 和 1 太過類似。

• 避免註釋。常常會出現代碼變了，註釋卻沒有更新的狀況。

人類讀者

• 名字要有 必要的長度 以表達精確的含義，可是應當 儘量短 以增長可讀性。

• 可讀性賽過簡潔性。CanScrollHorizontally 比 ScrollableX 好。

• 使代碼像 段落和句子 同樣可讀，並儘量正確地使用語法。

• 使用 讀得出來的名字，必須你能在聽起來不像白癡的狀況下討論它。例如，若是變量名爲 plhmbuster，你如何與別人討論它。

• 不要可愛或聰明。對於一個有趣的名字，只有當知情人還在項目團隊中的時候，它纔是可理解的。

• 使用可搜索的名字 以便 IDE 可以幫到你。例如，用常量表示魔數。

• 避免發音類似的名字。

• 避免容易拼錯的名字。