如何為您的變數、函數和類別寫出更好的名稱 – 附範例

命名是编写清晰、可维护和可扩展代码中最重要且具有挑战性的部分之一。一个深思熟虑的变量名，例如，可以作为自解释的代码，节省理解逻辑的时间和精力。但是，选择不当的名称，另一方面，可能导致混淆和错误。

本文将作为一个综合指南，介绍如何为类名、变量和函数提供有意义的名称，包括示例和最佳实践。

为什么命名很重要？

• 可读性：良好的名称使你的代码直观，并减少他人学习的曲线。

• 可维护性：更容易重构或调试良好命名的代码。

• 协作：清晰的名称提高团队沟通和生产力。

• 可扩展性：有意义的名称有助于保持大型项目的可管理性。

不同的命名约定风格

不同的命名约定风格在改善各种编程语言的代码可读性和可维护性方面至关重要。

像camelCase、PascalCase、snake_case和kebab-case这样的样式是根据特定的上下文和实践而定制的。

camelCase广泛用于变量和函数，而PascalCase更适用于类。snake_case在Python中因其清晰度而备受青睐，kebab-case在CSS中主导HTML元素的样式设置。

每种样式都确保了一致性，使代码对团队和未来开发人员更直观易懂。以下是一份关于一些流行命名约定的快速总结表，以及它们的用途和示例：

如何選擇合適的風格

1. 語言特定: 遵循您的編程語言或框架的慣例。例如:

   • JavaScript: camelCase 用於變量和函數，PascalCase 用於組件。

   • Python: snake_case 用於變量和函數。

   • CSS/HTML: kebab-case 用於類名和ID。

2. 團隊或項目標準: 一致性至關重要。使用團隊/項目中約定的風格。

3. 特定目的： 使用最佳代表被命名實體的命名風格（例如，常數使用SCREAMING_SNAKE_CASE）。

一般命名指南

在深入討論類別名稱、變數和函數的具體命名慣例之前，讓我們先探索一些普遍原則：

1. 具描述性且簡潔： 名稱應該傳達變數/函數等的目的或角色：

    // 不佳
    let x = 10;
   
    // 優良
    let maxUsersAllowed = 10;
   

2. 避免使用可能讓其他開發人員難以理解的簡寫（甚至是您未來的自己）：

    // 不好的寫法
    let usrNm = "John";
   
    // 好的寫法
    let userName = "John";
   

3. 使用一致的命名慣例：選擇一種命名風格（駝峰式、帕斯卡式、連字符、蛇式）並在整個項目中保持一致。

4. 避免使用保留關鍵字或令人困惑的名稱：

    // 不佳
    let let = 5;
   
    // 良好
    let variableName = 5;
   

好的，現在我們已經涵蓋了基本知識，讓我們深入探討一些有用的命名慣例。

如何創建良好的類別名稱

類別名稱定義了應用程序中元素的視覺或結構行為。撰寫清晰的類別名稱可確保您的 HTML 和 CSS 易於理解和維護。

1. 使用描述性名稱

類別名稱應該描述元素的目的，而不是它的外觀。

<!-- 不佳 -->
<div class="red-button"></div>

<!-- 良好 -->
<div class="primary-button"></div>

2. 遵循 BEM（區塊-元素-修飾符）方法論

BEM 是一種流行的編寫可擴展和可維護 CSS 的慣例。它將組件分為：

• 區塊: 代表元件（例如，card）。

• 元素: 代表區塊的子元素（例如，card__title）。

• 修飾符: 代表區塊或元素的變化（例如，card__title--highlighted）。

範例:

<div class="card">
  <h1 class="card__title card__title--highlighted">Welcome</h1>
  <p class="card__description">This is a card component.</p>
</div>

3. 使用 kebab-case

CSS 類名傳統上使用 kebab-case 寫法，以提高可讀性。

<!-- 不佳 -->
<div class="primaryButton"></div>

<!-- 好的 -->
<div class="primary-button"></div>

如何創建良好的變數名稱

變數保存數據，應該具有描述其代表的內容的有意義的名稱。

1. 使用名詞作為變數

變數通常是名詞，因為它們代表實體或數據。

// 不佳
let a = "John";

// 好的
let userName = "John";

2. 使用前綴添加上下文

添加前綴有助於澄清變數的類型或目的：

• 布林值: is, has, can

• 數字: max, min, total

• 陣列: 使用複數形式（例如，users, items）。

範例:

let isUserLoggedIn = true;
const maxUploadLimit = 5; // MB
const usersList = ["John", "Jane"];

3. 避免使用泛用名稱

除非必要，應避免使用像 data, value, 或 item 這樣的名稱。

// 不佳
let data = 42;

// 好
let userAge = 42;

如何創建良好的函數名稱

函數執行動作，因此它們的名稱應該反映它們執行的操作或過程。

1. 函數使用動詞

函數是以動作為導向的，因此它們的名稱應該以動詞開頭：

// 不佳
function userData() {
  // ...
}

// 好
function fetchUserData() {
  // ...
}

2. 具體說明功能

函數名應該表明其功能。

// 不好的
function handle() {
  // ...
}

// 好的
function handleFormSubmit() {
  // ...
}

3. 使用前綴表示意圖

• 對於事件處理程序：handle，on

• 對於工具程式：calculate，convert，format

• 對於獲取操作：fetch，get，load

• 對於設置器和獲取器：set，get

示例：

function handleButtonClick() {
  console.log("Button clicked!");
}

function calculateDiscount(price, discountPercentage) {
  return price * (discountPercentage / 100);
}

如何知道變量、函數或類的名稱是否適合好名稱

要了解名稱對於變量、函數或類是否合適並具有意義，重要的是使用幾個關鍵原則來評估它。以下是一個指南，幫助您決定名稱在編程上下文中是否合適和有意義：

1. 是否代表目的？

以目的為導向的命名是良好命名最重要的特徵。名稱應該立即告訴您變數、函數或類代表或執行的功能，而不需要閱讀額外的註釋或文件。

如何評估:

問自己：”當我讀這個名稱時，我能立即理解它的目的嗎？”

例子:

• userAge比a更好，因為userAge告訴您變數代表什麼，而a太模稜兩可。

2. 是否足夠具體？

名稱應該足夠具體以反映代碼中實體的確切角色。像data或temp這樣過於通用的名稱可能會令人困惑，因為它們並未提供足夠的上下文。

如何評估:

問：”這個名稱是否具體到足以反映變數、函數或類在我的應用中代表的內容？”

例子:

• calculateTaxAmount()比calculate()更好，因為清楚函數正在計算什麼。

3. 是否遵循一致的命名慣例？

命名慣例的一致性至關重要。當所有團隊成員遵循相同的慣例時，代碼更容易理解和導航。

如何評估:

請問：「這個名稱是否符合項目中使用的命名慣例？」遵循項目指南，例如：

• 駝峰命名法 用於變量和函數（例如，userAge）

• 帕斯卡命名法 用於類（例如，UserProfile）

• 全部大寫蛇形命名法 用於常數（例如，MAX_USERS）

範例：

• 如果您的團隊遵循駝峰命名法，則userData比UserData更好。

4. 是否避免歧義？

一個好名稱消除歧義。它不應該有多種解釋。如果在不同上下文中有不同的含義，會導致混淆。

如何評估：

詢問：「對於不熟悉代碼庫的人來說，是否可能誤解此名稱所指？」

範例：

• 不要將一個布爾值命名為isValid，而應該使用isUserLoggedIn或isEmailVerified來使檢查內容更清晰。

5. 易讀且易發音嗎？

儘管不是必需的，易讀性和發音可以提高代碼的整體可讀性和可維護性。

評估方法：

詢問：”這個名稱是否容易朗讀，一目了然？”

避免使用過長的名稱，僅在廣泛接受時使用常見縮寫。

範例：

• maxRetries比maximumNumberOfAttemptsToReconnect更好。

6. 是否避免了冗余？

避免在名稱中重複信息。不要重複已經被上下文暗示或描述的信息。

評估方法：

詢問：”我是否正在重複已經在周圍上下文中清晰的信息？”

範例：

• 如果你有一個名為User的類，將一個方法命名為userGetData()是多餘的。取而代之，使用getData()。

7. 是否自我描述？

最好的名稱自我描述。良好的名稱減少了需要額外註釋或解釋的需求。

評估方法：

詢問：”這個名稱是否完全描述了變數、函數或類，而無需注釋來解釋其功能？”

範例：

• calculateTotalPrice 是不言自明的，因此不需要额外添加注释，比如“此函数计算折扣后的总价格”。

8. 是否符合上下文和领域？

名称应符合项目及其领域的背景。例如，Web应用程序的命名约定可能与移动应用程序或机器学习模型的不同。

如何评估：

问：“这个名称是否与我的项目的领域和背景保持一致？”

如果您在特定领域（例如金融、健康、游戏）工作，请使用易于识别的领域专用术语。

示例：

• 在游戏应用中，healthPoints比hp更合适，因为它反映了其含义。

9. 是否具有未来性？

考虑您的代码将如何发展。名称应具有足够的灵活性，以适应未来的更改而无需重构。

如何评估：

问：“如果功能发生更改或项目增长，这个名称是否仍然合理？”

示例：

• userInfo如果数据结构发生更改，可能会过时。如果您预计会添加更多字段，则最好使用userProfile。

10. 是否避免使用魔法数字和硬编码的值？

魔術數字（意義不明的數字）應該避免使用，而應優先使用命名常數。

評估方式：

詢問：”這個名稱是否代表一個有意義的常數，或者只是一個原始數字？”

範例：

• 不要使用1000，而是使用一個像MAX_FILE_SIZE這樣的常數來解釋數字背後的含義。

實際範例

CSS範例

以下的CSS範例演示了如何應用BEM（區塊-元素-修飾符）命名慣例來在樣式表中保持結構化和可擴展的類別層級：

<!-- HTML -->
<div class="navbar">
  <ul class="navbar__list">
    <li class="navbar__item navbar__item--active">Home</li>
    <li class="navbar__item">About</li>
    <li class="navbar__item">Contact</li>
  </ul>
</div>

/* CSS */
.navbar {
  background-color: #333;
  padding: 10px;
}

.navbar__list {
  list-style: none;
}

.navbar__item {
  display: inline-block;
  padding: 10px;
}

.navbar__item--active {
  color: orange;
}

在這段代碼中正在發生的事情如下：

• BEM命名：navbar是區塊，代表主導航組件。

• navbar__list是元素，是該區塊的子元素，代表導航項目的列表。

• navbar__item是另一個元素，代表個別列表項目。

• navbar__item--active 是一個 修飾符，用於突出顯示當前活動的菜單項目。
  這種方法使得理解 HTML 和 CSS 之間的關係和角色變得容易，支持模組化和可重用的樣式。

JavaScript 示例

這個 JavaScript 示例展示了如何使用有意義且一致的命名慣例來為變數和函數命名，使代碼自我解釋：

// 變數
let isUserLoggedIn = false;
const maxAllowedItems = 10;

// 函數
function fetchUserDetails(userId) {
  // 從 API 獲取用戶數據
}

function calculateTotalPrice(cartItems) {
  return cartItems.reduce((total, item) => total + item.price, 0);
}

這段代碼的運作情況如下：

• 變數：

  • isUserLoggedIn：一個布林變數，命名清楚地指示其目的。以 is 開頭有助於識別它為布林值。

  • maxAllowedItems：一個以大寫 max 開頭的常量，顯示它是一個限制，使其意圖清晰。

• 函數:

  • fetchUserDetails(userId): 名稱反映了函數的目的，即檢索用戶詳細信息。參數 userId 是描述性的，避免了歧義。

  • calculateTotalPrice(cartItems): 函數名稱明確指出執行的動作。cartItems 參數與電子商務領域相關。

為什麼這樣做是好的：這些約定確保代碼可讀性和直觀性，減少其他開發人員在同一專案中工作的認知負擔。

結論

有意義的命名既是一種重要的約定，也是影響代碼可讀性和可維護性的藝術形式。

嘗試遵循這些基本原則：

• 使用描述性且簡潔的名稱。

• 遵循一致的約定，例如類名使用 BEM 和變數及函數使用 camelCase。

• 使用前綴以增強上下文和清晰度。

這些以及我們在這裡討論的其他提示將使您的代碼更易於使用，無論是幾個月後再次查看還是與團隊協作。今天就開始應用這些提示，看看您的代碼質量如何提升。