體面編碼之命名規則

banq發表於2018-12-31

體面編碼就是編寫更好程式碼的簡明指南，這是一份指南/清單，可幫助人們提高編碼和程式碼審查。

電腦科學中只有兩件事：快取失效和命名 - 菲爾卡爾頓

每個東西都有一個名稱，每個名稱只用於一件事。使用多個詞來表示相同的事物，或者同一個詞來表示不同的事物，會浪費認知的努力並且可能導致混淆。這不僅適用於程式碼，而且適用於我們工作環境中的所有內容，例如：變數和類名，方法名，資料，域概念，儲存庫，配置和許可權。

使用來自世界，商業和技術領域的知名人士。這樣做可以保持一個共同的詞彙表，使通訊更有效率。避免使用不同的含義過載這些名稱。

使用傳達意義的名稱。意義是能夠理解程式碼的關鍵。諸如“資料”或“值”之類的通用名稱資訊量較少。

避免讓來自其他上下文的不良/不一致的名稱蔓延到程式碼中。這樣的上下文包括遺留程式碼，庫和我們互動的其他應用程式。建立遵守這些命名準則的邊界，並保護其免受外部汙染。

面向使用者的名稱可以與眾不同。UI /輸出上顯示的名稱通常是需求，並顯示在他們自己的上下文中。如果從程式碼角度來看這些名稱很差或不合適，請儘可能使用不同的名稱。

謹慎使用首字母縮寫詞和縮寫詞。沒有它們，程式碼通常更清晰，更容易閱讀。像id一樣普遍接受的是這個規則的一個例外，包括來自業務領域的規則。

避免不必要的長名稱。目的不是為了傳達意義所需的時間。長名稱增加了對跨越多行的語句和方法呼叫的需求，這使得程式碼的可讀性降低。此規則意味著避免在不必要的情況下將型別的全名用作變數/引數名稱。

避免使用符合條件的名稱。當已經建立了名稱的上下文時，例如透過在類或方法中，沒有必要重新宣告該上下文。一個任務，例如，不需要taskCompleted。

對布林值使用正名，並避免名稱中的否定。否定名稱會導致雙重否定，這使得表達難以理解（考慮enabled: truevs. disabled: false）。使用“not”這個詞有同樣的問題。

避免過度使用“get”作為方法名稱字首。Getters返回值。在適當的情況下，更喜歡提供更多資訊性的替代方案，例如“請求”，“獲取”，“查詢”，“查詢”，“構建”或“建立”。

在同一背景下爭取獨特的名稱。類似的名稱很容易混淆，並且使程式碼難以閱讀。

當有必要對每個名稱進行限定時，請考慮對其進行限定。這通常產生更大的清晰度/獨特性，而不僅僅是限定它以區分它，並且使得更有可能選擇正確的一個用於適當的地方。示例：previousFoo＆nextFoo，而不是previousFoo＆foo。

考慮命名相關的東西，使它們按字母順序一起顯示。當使用字母順序約定時，這有助於發現。例如：data，dataError，dataLoaded。

方法應該始終做他們的名字所承諾的。方法名稱傳達了期望，如果不滿足，呼叫者將會感到驚訝。避免有條件地不做名稱所承諾的事情，並且如果無法做出名稱所承諾的事情則丟擲異常。

使用有意義的型別引數名稱，其中單個字母不清楚。這提高了可讀性。使用已建立的約定（例如“T”字尾）將它們與型別名稱區分開來。

避免使用camelCasing複合詞。它們本身就是單個單詞，所以不要求它。示例：回撥，密碼。
拼寫正確且一致。這樣做有助於避免錯誤，並提高程式碼搜尋能力。如果存在多個正確的拼寫（例如“顏色”），請遵循平臺慣例。

遵循您周圍的現有慣例。這些可能是特定的方法，程式碼庫作為一個整體，或您正在使用的技術/平臺。努力保持一致性，並避免在沒有充分理由的情

這個Gist可能很有用：在程式設計中往往有用的名稱列表

banq注：名稱採取英文駝峰寫法！
 

相關文章