JavaScript 编码风格指南

JavaScript 代码风格指南和编码规范

遵循一致的编码规范对于编写可读、可维护和协作的 JavaScript 代码至关重要。

JavaScript 编码规范

编码规范是一套关于编程风格方面的指导方针。它们通常涵盖：

• 变量、函数和类的命名和声明规则。
• 关于空格、缩进和注释的使用规则。
• 最佳编程实践和原则。

编码规范的好处：

• 提高代码可读性和清晰度。
• 简化代码维护和调试。
• 增强团队协作和一致性。

这些可以是团队的文档化规则（通常由 ESLint 等 Linter 和 Prettier 等格式化工具强制执行），也可以是您的个人编码实践。

	本页概述了常见的 JavaScript 编码规范。此外，还可以探索“最佳实践”以避免常见陷阱并编写更健壮的代码。

变量和函数命名

camelCase（驼峰式命名法）是 JavaScript 中变量和函数最常用的命名约定。

名称应以字母开头。它们也可以以 $ 或 _ 开头（尽管 _ 通常约定俗成地表示私有，但这并非语言强制的）。

对于不会被重新赋值的变量使用 const，对于会重新赋值的变量使用 let。在现代 JavaScript 中避免使用 var。

const firstName = "John";
const lastName = "Doe";
let price = 19.90;
const taxRate = 0.20; // 常量通常使用 camelCase 或 UPPER_SNAKE_CASE

function calculateTotalPrice(price, tax) {
  return price + (price * tax);
}

const fullPrice = calculateTotalPrice(price, taxRate);

对于真正的常量（固定且广泛使用的值），UPPER_SNAKE_CASE（大写蛇形命名法）也是一种常见的约定（例如，const MAX_USERS = 100;）。

运算符周围的空格

始终在运算符（=、+、-、*、/ 等）周围以及逗号后面添加空格，以提高可读性。

let x = y + z;
const values = ["Volvo", "Saab", "Fiat"];

for (let i = 0; i < 5; i++) {
  // ...
}

代码缩进

对代码块使用一致的缩进。2 个空格或 4 个空格是常见的选择。本指南使用 4 个空格。

function toCelsius(fahrenheit) {
    return (5 / 9) * (fahrenheit - 32);
}

	不要使用制表符进行缩进，因为不同的编辑器可能会有不同的解释。请配置您的编辑器将制表符转换为空格。

语句规则

简单语句的通用规则：

• 始终以分号结束简单语句。虽然 JavaScript 有自动分号插入 (ASI)，但显式分号可以避免歧义。

const items = ["Apple", "Banana", "Cherry"];
const user = {
    firstName: "Jane",
    lastName: "Doe",
    age: 30,
    email: "jane.doe@example.com"
};

复杂（复合）语句（例如，函数、循环、条件语句的代码块）的通用规则：

• 将开花括号 { 放在第一行的末尾。
• 在开花括号前使用一个空格。
• 将闭花括号 } 放在新的一行，与语句的开头对齐。
• 复杂语句块不要以分号结束。

function greet(name) {
    return `Hello, ${name}!`;
}

for (let i = 0; i < 5; i++) {
    x += i;
}

if (time < 20) {
    greeting = "Good day";
} else {
    greeting = "Good evening";
}

对象字面量规则

对象字面量定义的通用规则：

• 将开花括号放在与对象名称同一行（如果赋值给变量）。
• 在每个属性键和其值之间使用冒号加一个空格（例如，key: value）。
• 仅当字符串属性键不是有效标识符（例如，包含空格或连字符）或为了保持一致性时，才在其周围使用引号。现代 JavaScript 对于有效标识符键通常省略引号。
• 在字符串值周围使用引号，而不是在数字或布尔值周围。
• 考虑在多行对象的最后一个属性-值对后添加尾随逗号。这使得版本控制的差异更清晰，添加新属性也更容易。
• 将闭花括号放在新的一行，如果它是语句的结尾，则前面不要有空格。
• 以分号结束对象赋值语句。

const person = {
    firstName: "John",
    lastName: "Doe",
    age: 50,
    eyeColor: "blue", // 尾随逗号
};

// 较短的对象可以写在一行
const point = { x: 10, y: 20 };

行长度

为了可读性，尽量将行长度控制在 80-120 个字符以内。许多团队设置了上限（例如 100 个字符），并由 Linter 强制执行。

如果一个 JavaScript 语句不适合写在一行上，可以在运算符、逗号或开括号/花括号后换行。

document.getElementById("demo").innerHTML =
    "Hello Dolly, this is a longer line that has been wrapped.";

命名约定总结

努力在命名约定中保持一致性：

• 变量和函数名称：camelCase（驼峰式命名法）（例如，myVariable、calculateValue）。
• 类名称：PascalCase（帕斯卡命名法，也称为 UpperCamelCase）（例如，class UserAccount { ... }）。
• 常量（如果您喜欢用这种风格表示固定值）：UPPER_SNAKE_CASE（大写蛇形命名法）（例如，const API_KEY = "...";）。
• 私有属性/方法（约定俗成，非强制）：前缀加下划线 _（例如，_privateMethod()）。现代 JavaScript 使用 # 表示私有类字段（例如 #privateField）。

避免在 JavaScript 标识符中使用连字符，因为它们会被解释为减法。允许使用下划线，但 camelCase 对于大多数 JavaScript 名称来说更符合约定。

	不要以 $ 符号开头命名变量，除非您正在使用的库约定使用它（例如历史上的 jQuery）。现代 JavaScript 通常避免这样做。

在 HTML 中加载 JavaScript

使用简单的语法加载外部脚本。对于 <script> 标签来说，type="text/javascript" 属性不再是必需的，因为 JavaScript 是默认类型。

<!-- 推荐：将脚本放在 body 结束前，以获得更好的感知性能 -->
<script src="myscript.js"></script>

<!-- 或者使用 defer 确保 HTML 解析完成后再执行脚本 -->
<script src="anotherScript.js" defer></script>

<!-- Async 异步加载脚本，不阻塞 HTML 解析，加载完成后立即执行 -->
<script src="thirdScript.js" async></script>

了解 async 和 defer 属性以优化脚本加载。对于需要完整 DOM 的脚本，通常优先使用 defer。

访问 HTML 元素

选择 HTML 元素时，使用现代且高效的方法：

• 通过 ID 获取单个元素：document.getElementById('myId')
• 获取匹配 CSS 选择器的第一个元素：document.querySelector('.myClass') 或 document.querySelector('tag#id')
• 获取匹配 CSS 选择器的所有元素（返回一个 NodeList）：document.querySelectorAll('p.article')

虽然像 getElementsByTagName 和 getElementsByClassName 这样的旧方法仍然有效，但 querySelector 和 querySelectorAll 提供了更大的灵活性。

在您的 HTML（例如，id="user-profile"）和 JavaScript（例如，const userProfileElement = ...）之间使用一致的命名约定可以提高清晰度。

文件扩展名

使用标准文件扩展名：

• HTML 文件：.html
• CSS 文件：.css
• JavaScript 文件：.js（或在某些上下文中使用 .mjs 表示 ES Modules，使用 .cjs 表示 CommonJS）

使用小写文件名

Web 服务器可能区分大小写（例如，Unix 类系统上的 Apache、Nginx），也可能不区分大小写（例如，Windows 上的 IIS）。

为了避免在不同服务器环境之间部署或迁移项目时出现问题，请始终使用小写文件名（例如，mainscript.js、styles.css、about-us.html）。使用连字符进行分隔也很常见。

工具和性能

编码规范主要使人类开发者受益。大多数风格规则（缩进、空格）对未压缩代码的原始执行性能影响微乎其微。

对于开发而言，可读性至关重要。对于生产环境，JavaScript 代码应进行压缩（minified），以减小文件大小并缩短加载时间。Terser 或 Webpack 内置的压缩工具可以处理此事。

考虑使用 Linter（例如 ESLint）和格式化工具（例如 Prettier）来自动强制执行编码规范并及早捕获潜在错误。