如何为您的变量、函数和类编写更好的名称 – 附例子

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

本文将作为一份全面指南，介绍如何为类名、变量和函数制定有意义的名称，包括示例和最佳实践。

为什么命名很重要？

可读性：良好的名称使您的代码直观，减少他人的学习曲线。
可维护性：更容易重构或调试命名良好的代码。
协作：清晰的名称提高团队沟通和生产力。
可扩展性：有意义的名称有助于保持大型项目的可管理性。

不同的命名约定风格

在不同的编程语言中，采用不同的命名约定风格对于提高代码的可读性和可维护性至关重要。

像 camelCase、PascalCase、snake_case 和 kebab-case 的命名风格是针对特定上下文和实践量身定制的。

camelCase 在变量和函数中被广泛使用，而 PascalCase 则更适合用于类。snake_case 在 Python 中因其清晰性受到喜爱，而 kebab-case 在 CSS 中主导了 HTML 元素的样式。

每种风格都确保了一致性，使代码对团队和未来的开发者更直观。以下是一些流行命名约定的快速总结表，包含它们的使用案例和示例：

风格	示例	常见用法
camelCase	`userName`	变量、函数、对象属性
PascalCase	`UserName`	类、组件、构造函数
kebab-case	`primary-button`	CSS 类、HTML ID、文件名
snake_case	`user_name`	变量、Python 中的函数名
SCREAMING_SNAKE_CASE	`MAX_CONNECTIONS`	常量
dot.case	`config.file.path`	配置、键
Train-Case	`Primary-Button`	很少使用的标题
匈牙利命名法	`bIsActive`	遗留代码
大写字母带空格	`用户账户详情`	稀有，主要用于旧式文档
扁平化	`用户名`	极简，文件名，标识符

如何选择合适的风格

语言特定：遵循您编程语言或框架的约定。例如：
- JavaScript: camelCase 用于变量和函数，PascalCase 用于组件。
- Python: snake_case 用于变量和函数。
- CSS/HTML: kebab-case 用于类名和ID。
团队或项目标准：一致性是关键。使用团队/项目约定的风格。
特定于目的： 使用最能代表被命名实体的命名风格（例如，常量使用SCREAMING_SNAKE_CASE）。

通用命名指南

在深入探讨类名、变量和函数的具体命名约定之前，让我们先了解一些通用原则：

描述性和简洁： 名称应传达变量/函数等的目的或作用：

 // 不好的示例
 let x = 10;

 // 好的示例
 let maxUsersAllowed = 10;

避免使用可能让其他开发人员难以理解（甚至包括未来的自己）的神秘缩写：
```
 // 不好的写法
 let usrNm = "John";

 // 好的写法
 let userName = "John";
```
使用一致的命名约定：选择一种命名风格（驼峰式、帕斯卡式、短横线分隔式、下划线分隔式），并在整个项目中坚持使用。

避免使用保留关键字或混淆的名称：

 // 不好的写法
 let let = 5;

 // 好的写法
 let variableName = 5;

好了，现在我们已经介绍了基础知识，让我们深入了解一些有用的命名约定。

如何创建良好的类名

类名定义应用程序中元素的视觉或结构行为。编写清晰的类名确保您的 HTML 和 CSS 易于理解和维护。

1. 使用描述性名称

类名应描述元素的目的，而不是其外观。

<!-- 不好的写法 -->
<div class="red-button"></div>

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

2. 遵循 BEM（Block-Element-Modifier）方法论

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. 使用短横线命名法

CSS 类名通常使用短横线命名法，以提高可读性。

<!-- 不好 -->
<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，为变量和函数使用驼峰命名法。
使用前缀添加上下文和清晰度。

我们在这里讨论的这些建议和其他技巧将使您的代码在几个月后或与团队合作时更易处理。从今天开始应用这些建议，看着您的代码质量飞速提升。