程式設計命名規範（網文）

love/coder發表於2024-11-19
程式設計

一個好的變數或函式命名，應該能起到自解釋的作用，甚至能減少我們程式碼的註釋。

naming-cheatsheet是一個命名備忘錄，記錄一些常見的規範約定，並提供簡單的例子說明。如果能夠嚴格遵守這些規範，相信我們的程式碼可讀性會大大提升，下面就來介紹 naming-cheatsheet 提供的一些建議。

專案地址：

https://github.com/kettanaito/naming-cheatsheet

使用英語

這是最基本的一條規則了，英語是程式設計中的主要語言，所有程式語言的語法都是用英語編寫的，透過英語編寫程式碼，可以大大提高其通用性。對於我們國內開發者來說，一定要避免拼音甚至是直接的中文命名。

/* Bad */
const primerNombre = 'Gustavo'
const amigos = ['Kate', 'John']

/* Good */
const firstName = 'Gustavo'
const friends = ['Kate', 'John']

命名風格

選擇一種命名的風格，並且嚴格遵守，可以是camelCase，或者snake_case，或者是其他任何的風格，最重要的是要保持一致，不管是個人開發者還是團隊，保持一致的命名風格很重要，不要混合使用。

/* Bad */
const page_count = 5
const shouldUpdate = true

/* Good */
const pageCount = 5
const shouldUpdate = true

/* Good as well */
const page_count = 5
const should_update = true

遵守SID原則

命名應該簡短、直觀並且具有描述性，遵循SID原則。

  • Short。簡短，避免輸入太長，但是也應該注意不能簡寫到失去其原本的意義。
  • Intuitive。直觀，並且儘可能接近自然語言。
  • Descriptive。以最有效的方式反映其作用或目的。
/* Bad */
const a = 5 // "a" could mean anything
const isPaginatable = a > 10 // "Paginatable" sounds extremely unnatural
const shouldPaginatize = a > 10 // Made up verbs are so much fun!

/* Good */
const postCount = 5
const hasPagination = postCount > 10
const shouldPaginate = postCount > 10 // alternatively

避免過度的簡寫

命名要簡短，但是要避免鑽牛角尖，命名最重要的是要讓人能看懂，過度的縮寫如果失去了其原本的意義，降低了程式碼的可讀性，那就不應該這麼做，寧願多寫幾個字母。

/* Bad */
const onItmClk = () => {}

/* Good */
const onItemClick = () => {}

避免上下文重複

有時候在一段程式碼中可能會出現類似意義的變數定義，這個時候要避免命名的重複。

class MenuItem {
  /* Method name duplicates the context (which is "MenuItem") */
  handleMenuItemClick = (event) => { ... }

  /* Reads nicely as `MenuItem.handleClick()` */
  handleClick = (event) => { ... }
}

反映預期結果

變數或函式的命名應該能反映預期的結果。

/* Bad */
const isEnabled = itemCount > 3
return <Button disabled={!isEnabled} />

/* Good */
const isDisabled = itemCount <= 3
return <Button disabled={isDisabled} />

命名的模式

可以參考以下類似的模式來做命名。

A/HC/LC模式

可以遵循A/HC/LC，即

prefix? + action (A) + high context (HC) + low context? (LC)
nameprefixAHCLC
getUser get User
getUserMessages get User Messages
handleClickOutside handle Click Outside
shouldDisplayMessage should Display Message

上下文的順序可能會影響變數的含義，例如shouldUpdateComponent意味著將要更新一個元件，換一下順序變成shouldComponentUpdate，意味著元件將做自我更新。

動作

函式名稱的動詞部分，是描述函式作用的最終要的部分，如：

  • getXXX，表示獲取資料
  • setXXX，表示設值
  • resetXXX，重置資料
  • fetchXXX，請求資料
  • removeXXX，移除資料，表示從某處刪除某物
  • deleteXXX，刪除資料，表示完全清楚某些事物
  • composeXXX，從現有資料建立新資料
  • handleXXX，處理某個動作

上下文

函式或方法通常是某些事物的動作，結合上下文，能夠明確其操作的物件，或者要能反映出函式預期的資料型別。一些特定的情況下允許省略上下文，例如在JavaScript中，filter對Array進行操作很常見，就沒必要命名為filterArray了。

/* A pure function operating with primitives */
function filter(predicate, list) {
  return list.filter(predicate)
}

/* Function operating exactly on posts */
function getRecentPosts(posts) {
  return filter(posts, (post) => post.date === Date.now())
}

字首

字首用來增強變數的含義，如：

  • is，描述特徵或狀態，通常是boolean型別
  • has，描述是否具有某個狀態或值，通常是boolean型別
  • should，反映肯定的條件，加上特定的執行動作
  • min/max，描述邊界或界限時使用
  • prev/next，指示前一個或下一個狀態

單複數

變數名稱是單數還是複數，取決於值的單數還是複數。

/* Bad */
const friends = 'Bob'
const friend = ['Bob', 'Tony', 'Tanya']

/* Good */
const friend = 'Bob'
const friends = ['Bob', 'Tony', 'Tanya']

網文地址

相關文章