跳到主要内容

附录 A：前端工程化文件与变量命名规范

在现代软件工程中，命名不仅仅是个人习惯问题，更是团队协同开发中的“最高法律契约”。极其严谨的命名规范能够极大降低代码的认知负荷（Cognitive Load），提升 Git 版本控制的合并效率，并从根本上杜绝跨平台部署时的寻址灾难。

本规范汇编了工业界最通用的前端资产与变量命名法则，供开发者在项目全生命周期中查阅与严格遵守。

一、 物理文件与目录架构命名法则​

前端工程的物理文件直接映射到操作系统的文件树与 Web 服务器的 URL 路由。其命名必须具备极高的跨平台兼容性与 URL 安全性。

1. 核心铁律​

  • 绝对禁用中文字符：严禁在任何目录、HTML、CSS、JS 及多媒体资产中使用中文命名。中文在通过 HTTP 协议传输时会被强制进行 UTF-8 编码（如 %E4%B8%AD），极易导致跨操作系统（从 Windows 开发机到 Linux 生产服务器）部署时出现乱码或 404 Not Found 寻址断裂。
  • 全小写原则（Lowercase Only）：Windows 系统对文件名大小写不敏感，而 Linux 系统严格区分大小写。为避免跨端协作时的版本控制冲突，所有前端物理目录与文件名必须 100% 采用纯小写英文字母。

2. 多单词连接法则（Kebab-case）​

当文件名由多个逻辑单词组成时，**强制使用中划线（连字符 -）**进行连接，严禁使用空格、下划线（_）或驼峰拼写法。

  • 合规示例：user-profile.html、main-layout.css、shopping-cart.js、hero-banner.jpg。
  • 违规示例：user profile.html（含空格）、UserProfile.js（含大写）、main_layout.css（下划线在某些旧版搜索引擎爬虫中解析不友好）。

3. 标准资源池目录拓扑​

  • styles/ 或 css/：存放全局与局部层叠样式表。
  • scripts/ 或 js/：存放客户端交互与逻辑引擎脚本。
  • images/ 或 img/：存放矢量图（SVG）、位图（JPG/PNG/WebP）及动画资产。
  • assets/：存放除代码外的其他静态物理资产（如字体文件 fonts/）。

二、 CSS 视图层类名（Class）规范​

CSS 类名是连接 HTML 语义骨架与视觉渲染层的桥梁。在组件化开发中，推荐采用**BEM（Block, Element, Modifier）**命名方法论或高度语义化的短横线命名法。

1. 语义化优先而非视觉优先​

类名必须描述该区块的“业务功能（它是什么）”，而不是“视觉表现（它长什么样）”。

  • 合规示例：.alert-error、.nav-primary、.submit-btn。
  • 违规示例：.red-text、.float-left、.big-font（当 UI 设计稿变更时，这些类名将失去意义并产生认知混乱）。

2. BEM 架构方法论（进阶推荐）​

在复杂微组件开发中，利用 BEM 规范可以实现 CSS 作用域的物理隔离，彻底解决样式污染问题。

  • Block（区块）：独立的业务组件实体。如 .card。
  • Element（元素）：区块内部的不可分割节点，使用双下划线连接。如 .card__title、.card__image。
  • Modifier（修饰符）：描述区块或元素的状态机变化，使用双中划线连接。如 .card--active、.card__title--highlight。

三、 JavaScript 逻辑层变量与函数规范​

JavaScript 承载了系统的底层状态与交互逻辑。其命名必须遵循经典的 ECMAScript 范式，做到“见名知意”。

1. 小驼峰命名法（lowerCamelCase）​

适用于绝大多数的普通变量、对象实例与普通函数。首字母小写，后续每个逻辑单词的首字母大写。

  • 变量示例：userData、currentOrderPrice、shoppingCart。
  • 函数示例：getUserProfile()、calculateTotal()、renderMatrix()。

2. 大驼峰命名法 / 帕斯卡命名法（UpperCamelCase / PascalCase）​

专用于类（Class）、构造函数（Constructor）以及前端框架中的组件对象（Component）。

  • 合规示例：class UserAccount { ... }、function Employee() { ... }、HeaderComponent。

3. 全大写蛇形命名法（UPPER_SNAKE_CASE）​

专用于在系统运行生命周期内绝对不可更改的全局静态常量（Constants）或枚举值。所有字母大写，单词间以下划线连接。

  • 合规示例：const MAX_RETRY_COUNT = 3;、const API_BASE_URL = 'https://api.example.com';。

4. 状态机与布尔值（Boolean）专用前缀​

描述真假状态的变量，必须强制使用特定的动词前缀（is、has、can、should）提出疑问，以提高逻辑代码的可读性。

  • is（是否具有某种状态）：isVisible、isValid、isLoggedIn。
  • has（是否包含某项元素）：hasError、hasChildren。
  • can / should（是否允许或应该执行操作）：canSubmit、shouldUpdate。

5. 事件侦听器（Event Handlers）规范​

在进行 DOM 交互事件绑定时，回调函数通常以 handle 或 on 为前缀，配合具体的事件类型与业务目标。

  • 合规示例：handleClick（处理点击）、onSubmitForm（表单提交时触发）、handleUserScroll（处理用户滚动）。

四、 团队工程化协同防腐原则​

除了具体的拼写法则，所有前端工程师在编码时还需时刻守住以下“防腐（Anti-Corruption）”底线：

  1. 拒绝无意义的缩写：除非是业界公认的绝对标准缩写（如 id、url、html、api），否则严禁擅自缩写（例如将 navigation 缩写为 nvg，将 password 缩写为 pswd）。宁可变量名长达 30 个字符，也决不允许牺牲代码的语义清晰度。
  2. 消灭魔法数字（Magic Numbers）：严禁在逻辑代码中直接硬编码难以理解的数字字面量。
    • 违规（魔法数字）：if (status === 2) { ... }
    • 合规（状态提纯）：const STATUS_VERIFIED = 2; if (status === STATUS_VERIFIED) { ... }