軟體開發命名指南

yuanhjty發表於2019-03-31

摘譯自 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 能夠幫到你。例如，用常量表示魔數。

  • 避免發音相似的名字。

  • 避免容易拼錯的名字。

相關文章