命名约定：用于清晰、可扩展代码的指南

发现掌握编程中的命名约定如何带来更干净、更可扩展的代码。学习实用规则、自动化和推广策略。

介绍

命名约定不仅仅是风格选择——它们是使代码可读、可维护并且更安全以便变更的共用语言。好的名称可以减少心理负担、加速入职，并改进从 linters 到 AI 助手的自动化。此指南提供针对 TypeScript、React 和 Node 的实用规则，以及使约定生效的强制和推广策略。

为什么命名约定是代码库的第一道防线

命名不是关于美学；而是关于清晰沟通。每个变量、函数和组件都是你应用故事的一部分。模糊或不一致的名称迫使阅读者停下来寻找上下文，把小修小补变成耗时的工作。

单个不明确的函数名可以导致数分钟或数小时的调试浪费。当这种情况在团队中反复出现时，生产力下降、事故发生的可能性增加。具有清晰、一致命名的代码库会变得有效地“自我文档化”，减少对冗长注释的需求，并使系统更易于导航。

命名不良的现实成本

考虑一个带有名为 processItem() 的函数和名为 dataList 参数的 Node.js 后端。它实际上做了什么？为了解答，你可能需要阅读实现、追踪调用方或运行调试器。这些绕路会累加，并在假设不明确时导致真实故障。

对早期项目的审计发现命名方面普遍不一致，并且在入职和调试工作上出现了可测量的减慢，这凸显了命名如何影响团队速度和可靠性。¹

加拿大统计局也强调了一致标准如何减少政府项目中的集成错误，证明命名和标准化在大规模场景下很重要。²

命名约定与团队可扩展性

随着团队增长，问题会加剧。命名不一致会使新成员更难理解代码并降低协作速度。尽早采纳共享约定可以防止留下遗留债务并在扩展时减少摩擦。

常见命名风格一览

此速查表展示了常见的大小写风格及其典型使用场景：

理解何时使用每种风格可以在整个项目中建立可预测的词汇表。

为与 AI 协作准备代码

像 GitHub Copilot 和 Cursor 这样的 AI 工具在一致的代码下效果最佳。它们从你的代码库中学习模式并在建议中反映这些模式。

• 可预测的 AI 建议：以 is 或 has 为前缀的布尔值可以带来更清晰的条件逻辑。
• 准确的函数生成：始终使用 fetchSomething 类似命名来获取数据，能帮助 AI 生成正确的异步代码。
• 更智能的重构：一致的名称帮助工具检测关系并产生更安全的变更。

通过明确命名约定，你不仅提高了人工可读性，还让你的 AI 助手成为更可靠的协作者。

针对 TypeScript、React 和 Node 的实用命名规则

这些规则经受过现代 Web 技术栈的实战检验，可减少团队的认知负担。

核心 JavaScript 与 TypeScript 约定

• 变量和函数：使用 camelCase

  • 好：let userProfile = {};
  • 好：function calculateTotalPrice() {}
  • 不好：let UserProfile = {};（看起来像类）

• 类、接口、类型：使用 PascalCase

  • 好：class AuthenticationService {}
  • 好：interface User { id: string }

• 真正的常量：使用 UPPER_SNAKE_CASE

  • 好：const API_BASE_URL = '...'
  • 好：const MAX_LOGIN_ATTEMPTS = 5;

把这些基本规则做到位会使标识符立即可识别。

语义化命名以提高清晰度

使用能表明意图的词汇和前缀。变量与函数之间的清晰区分能减少错误和误解。研究和审计显示，采用明确命名的团队会降低 bug 率并提高可维护性。³

React 专用规则

• 组件和文件名：使用 PascalCase

  • function UserProfile() { ... } → 文件 UserProfile.tsx

• 事件处理器：以 handle 为前缀

  • function handleLoginClick() { ... }

• useState 配对：遵循 [thing, setThing]

  • const [isLoading, setIsLoading] = useState(false);

面向动作与描述性的命名

• 布尔值：以 is、has 或 can 为前缀（isModalOpen、hasUnsavedChanges）
• 函数：使用动词命名（fetchUserData、validateInput、saveSettings）

采用像普通英语一样可读的命名——这会让代码更直观并减少注释需求。

自动化一致性以强制命名规则

定义规则是第一步；自动化让它们长期生效。单靠代码审查来维持命名一致浪费审查者时间且容易出空档。

ESLint：你的第一道防线

ESLint 在编辑器中提供实时反馈，并可以通过自定义规则或插件来强制命名规则。使用共享的 ESLint 配置以便每个人获得相同的检查。

• 实时修正可在提交前防止错误。
• 定制规则可强制团队特定约定（例如布尔前缀）。
• 共享配置消除风格争论并减少摩擦。

使用 Husky 的 pre-commit 钩子

Husky 在提交时运行脚本。结合 lint-staged，它通过对暂存文件运行 ESLint 并拒绝不符合检查的提交，防止不合规代码进入仓库。

CI Linting

在 CI 中始终运行 linter 作为最终门槛。CI 充当客观的事实源，并阻止引入命名违规或其他风格错误的拉取请求。

这三层方法——编辑器 lint、pre-commit 钩子和 CI——以最低的手工监管强制标准。

设计你的文件和文件夹结构

命名约定延伸到文件和目录。可预测的架构帮助新开发者快速找到代码，并在进行变更时减少认知负担。

按功能组织，而非按类型组织

围绕功能或领域来组织代码，而不是按文件类型。将某个功能的组件、服务、hook 和测试放在同一目录下。例如，把所有与身份验证相关的内容放在 /auth 中。

这使功能自包含，更易于理解、测试或删除。

基本文件命名规则

• 目录：使用 kebab-case（user-profile、auth-service）
• React 组件：PascalCase（UserProfile.tsx）
• 工具与服务：camelCase（apiClient.ts、stringUtils.ts）
• 使用描述性后缀（.test.ts、.stories.tsx、.styles.ts）

一致的文件系统可以减少合并冲突并帮助分布式团队协作。

如何在现有代码库中推广新约定

全面、即时的重构风险很大。相反，采用渐进式方法：总是把代码留得比你找到时更干净一点。

从对话开始

通过解释可量化的好处来获得团队认同：更快的入职、更少的 bug 以及更高的开发者生产力。在单个模块上运行试点以演示收益并建立动力。

记录规则

把约定写入 CONTRIBUTING.md 或项目 README。使用清晰的示例展示正确与错误。简要解释理由以便规则得以固化。

让 linter 干繁重的活

将工具配置为仅在新代码或变更过的代码上强制规则：使用 lint-staged、Husky 和仅针对 PR 变更的 CI 检查。这避免在大型遗留文件上阻塞工作，同时确保所有新变更遵循标准。

衡量成功

跟踪以下信号：

• 关于命名的 PR nit 评论减少
• 审查周期更快
• 新员工的入职反馈更好

这些指标表明你的约定是否在提升团队速度和代码清晰度。

关于命名约定的常见问题

如何让资深开发者认可？

侧重于团队层面的好处而非个人偏好。使用审计或试点重构的数据来展示在可读性和审查时间上的具体改进。让它成为团队共同决定，而不是自上而下的命令。

API 端点最好的命名约定是什么？

对于 RESTful API，资源使用复数名词，并让 HTTP 方法定义动作。示例：GET /users、GET /users/{userId}、POST /users。避免在 URL 中使用动词，以保持 API 的可预测性和语言无关性。

测试文件应该有自己的命名约定吗？

是的。镜像组件或模块名并添加 .test.ts 或 .spec.ts。将测试放在它们所覆盖的文件旁边，并编写像自然语言句子一样可读的测试描述。

快速问答 — 三个简明回答

问：最有影响力的单一命名规则是什么？

答：对变量/函数使用 camelCase，对类型/组件使用 PascalCase，对真正的常量使用 UPPER_SNAKE_CASE。这些视觉线索本身就能显著减少混淆。

问：如何在不破坏遗留代码构建的情况下强制命名？

答：将 lint 配置为仅对暂存或变更文件运行（使用 lint-staged 和仅针对 PR 的 CI 检查）。这对新工作强制规则，同时允许以渐进方式改进遗留代码。

问：命名约定如何帮助像 Copilot 这样的 AI 工具？

答：一致的模式教会 AI 项目的意图，因此建议更准确、重构更安全、生成的代码遵循团队既定的约定。

在 Clean Code Guy，我们帮助团队采纳实用标准并运行代码库审计与 AI 就绪重构，以将结构和速度带回工程团队。了解更多请访问 https://cleancodeguy.com。

保持所有 markdown 格式、链接和代码块与原文完全一致。