JavaScript 代码示例编写指南

以下指南涵盖了如何为 MDN Web Docs 编写 JavaScript 示例代码。本文列出了编写简洁示例的规则，以期这些示例将被尽可能多的人理解。

JavaScript 代码示例常规指南

本节解释了编写 JavaScript 代码示例时要牢记的一般准则。后面的部分将涵盖更具体的细节。

选择格式

关于正确缩进、空格和行的长度方面的观点一直存在争议。对这些主题的讨论会分散创作和维护内容的注意力。

在 MDN Web Docs，我们使用 Prettier 作为代码格式化工具以保持代码样式的一致性（同时避免偏离主题的讨论）。你可以查阅我们的配置文件了解当前规则，并阅读 Prettier 文档。

Prettier 格式化所有代码并保持风格一致。尽管如此，你还需要遵守一些额外的规则。

使用现代 JavaScript 特性

如果新的特性被每个主流的浏览器——Chrome、Edge、Firefox 和 Safari 所支持，你就可以使用它们。

数组

创建数组

请使用字面量而非构造函数来创建数组。

像这样来创建数组：

const visitedCities = [];

而不要这样创建数组：

const visitedCities = new Array(length);

添加元素

向数组添加元素时，请使用 push() 而非直接赋值。考虑有如下数组：

const pets = [];

像这样向数组添加元素：

pets.push("cat");

而不要像这样向数组添加元素：

pets[pets.length] = "cat";

异步方法

编写异步代码可以提高性能，应尽可能使用。特别是，你可以使用：

当两种语法都可行时，我们倾向于使用更简单的 async/await 语法。不幸的是，你不能在顶层使用 await，除非你在 ECMAScript 模块中。但 Node.js 使用 CommonJS 模块而不是 ES 模块。因此，如果你打算在所有地方使用该示例，请避免顶层的 await。

注释

注释对于编写良好的代码示例非常重要。它们清楚地阐明了代码的意图，并帮助开发者理解它。因此要特别注意它们。

如果代码的目的或逻辑不明显，请添加表明你的意图的注释，就像下面这样：

let total = 0;

// 计算数组 arr 的前四个元素的和
for (let i = 0; i < 4; i++) {
  total += arr[i];
}

另一方面，请不要用文字重述代码来作为注释：

let total = 0;

// 从 1 到 4 的 for 循环
for (let i = 0; i < 4; i++) {
  // 将值累加到总和（total）
  total += arr[i];
}

当函数的名称清楚地描述了它们的作用时，不需要再注释。如：
js
```
closeConnection();
```
不要写像下面这样的注释：
js
```
closeConnection(); // 关闭连接
```

使用单行注释

单行注释用 // 标记，与包含在 /* … */ 之间的块注释相反。

通常情况下，使用单行注释来注释代码。编写者必须用 // 标记每一行的注释，这样就更容易直观地注意到注释掉的代码。此外，这种约定允许在调试时使用 /* … */ 注释掉部分代码。

在斜杠和空格之间留一个空格。（英文的）注释以大写字母开头，就像句子一样，但不要在结尾加句号。
js
```
// 这是一个良好的单行注释
```

如果一个注释没有在新缩进级别之后开始，请在空行后添加注释。这将创建一个代码块，使得注释与代码的关联更加清晰。此外，将你的注释放在它们所指的代码之前的单独一行上。如下例所示：

function checkout(goodsPrice, shipmentPrice, taxes) {
  // 计算总价
  const total = goodsPrice + shipmentPrice + taxes;

  // 创建一个文档并向其添加一个新的段落
  const para = document.createElement("p");
  para.textContent = `总价是 ${total}`;
  document.body.appendChild(para);
}

打印的输出

对于预期在生产环境中运行的代码，你很少会需要对打印语句进行注释。在代码示例中，我们经常使用 console.log()、console.error() 或类似的函数来输出重要的值。为了帮助读者在不运行代码的情况下理解会发生什么，你可以在打印函数之后注释输出的内容。比如：
js
```
function exampleFunc(fruitBasket) {
  console.log(fruitBasket); // ['香蕉', '芒果', '橙子']
}
```
请不要这样写：
js
```
function exampleFunc(fruitBasket) {
  // 输出：['香蕉', '芒果', '橙子']
  console.log(fruitBasket);
}
```

如果这样会让行变得太长，请将注释放在函数之后，如下所示：

function exampleFunc(fruitBasket) {
  console.log(fruitBasket);
  // ['香蕉', '芒果', '橙子', '苹果', '梨', '榴莲', '柠檬']
}

多行注释

简短的注释通常更好，所以尝试将他们保持在 60–80 个字符的单行中。如果这不可能，请在每行的开头使用 //：

// 这是一个多行注释的示例。
// 假设下面的函数有一些我想指出的不寻常的局限性。
// 局限 1
// 局限 2

请不要使用 /* … */：

/* 这是一个多行注释的示例。
  假设下面的函数有一些我想指出的不寻常的局限性。
  局限 1
  局限 2 */

使用注释来标记省略号

为了保持示例简短，我们需要使用省略号（…）来跳过冗余代码。尽管如此，编写者应该仔细考虑，因为开发者经常复制粘贴示例到他们的代码中，所以我们所有的示例代码都应该是有效的 JavaScript。

在 JavaScript 中，你应该将省略号（…）放在注释之中。可能的话，请指出重用此代码片段的人预计会添加什么操作。

对省略号（…）使用注释更加明确，可以防止开发人员复制和粘贴示例代码时出现错误。比如：

function exampleFunc() {
  // 在此处添加你的代码
  // …
}

请不要像这样这样使用省略号（…）：

function exampleFunc() {
  …
}

注释掉参数

在编写代码时，你通常会省略你不需要的参数。但在某些代码示例中，你想要显式的说明你没有使用某些可能的参数。

为此，请在参数列表中使用 /* … */。这是只使用单行注释（//）的规则的一个例外。

array.forEach((value /* , index, array */) => {
  // …
});

函数

函数名称

对于函数名称，请使用以小写字母开头的小驼峰式命名。酌情使用简洁、可读的和语义化的名称。

以下是函数名称的正确示例：

function sayHello() {
  console.log("你好！");
}

请不要使用像这样的函数名称：

function SayHello() {
  console.log("你好！");
}

function doIt() {
  console.log("你好！");
}

函数声明

在可能的情况下，请使用函数声明而不是函数表达式来定义函数。以下是声明函数的推荐方式：
js
```
function sum(a, b) {
  return a + b;
}
```
以下不是定义函数的好方法：
js
```
let sum = function (a, b) {
  return a + b;
};
```
当使用匿名函数作为回调（传递给另一个方法调用的函数），如果你不需要访问 this，使用箭头函数可以让代码更加简洁明了。以下是推荐的方式：
js
```
const array1 = [1, 2, 3, 4];
const sum = array1.reduce((a, b) => a + b);
```
而不是这样：
js
```
const array1 = [1, 2, 3, 4];
const sum = array1.reduce(function (a, b) {
  return a + b;
});
```
考虑避免使用箭头函数将函数分配给标识符。尤其是，不要对方法使用箭头函数。使用带有关键字 function 的函数声明：
js
```
function x() {
  // …
}
```
不要这样：
js
```
const x = () => {
  // …
};
```
使用箭头函数时，尽可能使用隐式返回（也称为表达式主体）：
js
```
arr.map((e) => e.id);
```
而不是：
js
```
arr.map((e) => {
  return e.id;
});
```

循环和条件语句

循环初始化

当需要循环时，从 for(;;)、for...of、while 等中选择合适的。

在遍历集合中的所有元素时，避免使用传统的 for (;;) 循环；优先使用 for...of 或 forEach()。请注意，如果你使用的是一个不是 Array 的集合，你必须检查 for...of 是否真的被支持（它需要变量是可迭代的），或者 forEach() 方法是否存在。使用 for...of：
js
```
const dogs = ["旺财", "来福"];
for (const dog of dogs) {
  console.log(dog);
}
```
或 forEach()：
js
```
const dogs = ["旺财", "来福"];
dogs.forEach((dog) => {
  console.log(dog);
});
```
请不要使用 for (;;)——你不仅需要添加额外的索引 i，你还必须跟踪数组的长度。这对于初学者来说很容易出错。
js
```
const dogs = ["旺财", "来福"];
for (let i = 0; i < dogs.length; i++) {
  console.log(dogs[i]);
}
```
确保你正确地定义了初始化器，对 for...of 使用 const 关键字，或对其他循环使用 let。注意不要遗漏。以下是正确的示例：
js
```
const cats = ["汤姆", "胖橘"];
for (const cat of cats) {
  console.log(cat);
}

for (let i = 0; i < 4; i++) {
  result += arr[i];
}
```
下面的示例没有遵循推荐的初始化准则（它隐式创建了全局变量，并且在严格模式下会失败）：
js
```
const cats = ["汤姆", "胖橘"];
for (i of cats) {
  console.log(i);
}
```

但是需要同时范围值和索引时，你可以使用 .forEach() 而不是 for (;;)。例如：

const gerbils = ["舒克", "贝塔"];
gerbils.forEach((gerbil, i) => {
  console.log(`沙鼠 ${i} 号：${gerbil}`);
});

请不要这样写：

const gerbils = ["舒克", "贝塔"];
for (let i = 0; i < gerbils.length; i++) {
  console.log(`沙鼠 ${i} 号：${gerbil}`);
}

警告： 切勿使用 for...in 遍历数组和字符串。

备注： 考虑完全不使用 for 循环。如果你正在使用 Array（或者在某些操作中使用 String），请考虑使用更具语义的迭代方法，比如 map()、every()、findIndex()、find()、includes() 等。

控制语句

对于 if...else 控制语句，有一个值得注意的情况。如果 if 语句以 return 结尾，则不要添加 else 语句。

在 if 语句后继续，例如：

if (test) {
  // 如果 test 为真则执行某些操作
  // …
  return;
}

// 如果 test 为假则执行某些操作
// …

请不要这样写：

if (test) {
  //  如果 test 为真则执行某些操作
  // …
  return;
} else {
  // 如果 test 为假则执行某些操作
  // …
}

将大括号与控制流语句和循环一起使用

虽然像 if、for 和 while 的控制流语句不需要在内容中只有一个语句时使用大括号，但你总是应该使用大括号。比如：

for (const car of storedCars) {
  car.paint("红色");
}

不要这样写：

for (const car of storedCars) car.paint("红色");

这可以防止忘记在添加更多语句时添加大括号。

Switch 语句

switch 语句可能有点棘手。

不要在 return 语句后添加 break 语句。相反，请像下面这样编写 return 语句：

switch (species) {
  case "chicken":
    return farm.shed;
  case "horse":
    return corral.entry;
  default:
    return "";
}

如果你添加了 break 语句，它会是不可达的。不要这样写：

switch (species) {
  case "chicken":
    return farm.shed;
    break;
  case "horse":
    return corral.entry;
    break;
  default:
    return "";
}

使用 default 作为最后一个 case，不要在 default 后面添加 break 语句。如果你需要做不同的事情，请添加注释来解释为什么。

请记住，当你为一个 case 声明一个局部变量时，你需要使用大括号来定义作用域：

switch (fruits) {
  case "Orange": {
    const slice = fruit.slice();
    eat(slice);
    break;
  }
  case "Apple": {
    const core = fruit.extractCore();
    recycle(core);
    break;
  }
}

错误处理

如果程序的某些状态引发未捕获的错误，它们会停止执行，并可能降低示例的可用性。因此，你应该使用 try...catch 块来捕获错误，如下所示：
js
```
try {
  console.log(getResult());
} catch (e) {
  console.error(e);
}
```

在你不需要 catch 语句的参数时，请省略它：

try {
  console.log(getResult());
} catch {
  console.error("发生了一个错误！");
}

备注： 请记住，只有可恢复的错误才应该被捕获和处理。所有不可恢复的错误都应该被抛出，并在调用栈中逐级向上冒泡。

对象

对象名称

当定义一个类时，使用大驼峰式（以大写字母开头）来命名类，使用小驼峰式（以小写字母开头）来命名对象属性和方法名。

当定义一个对象实例时，使用字面量或构造函数，请使用小驼峰式（以小写字母开头）为实例命名。比如：

const hanSolo = new Person("Han Solo", 25, "he/him");

const luke = {
  name: "Luke Skywalker",
  age: 25,
  pronouns: "he/him",
};

创建对象

对于创建普通对象（即，当不涉及类时），请使用字面量而非构造函数。

例如，这样做：

const object = {};

不要像这样创建普通对象：

const object = new Object();

对象类

使用新的 ES 类语法进行定义，而不是构造函数。例如，这是推荐的方式：

class Person {
  constructor(name, age, pronouns) {
    this.name = name;
    this.age = age;
    this.pronouns = pronouns;
  }

  greeting() {
    console.log(`你好！我是 ${this.name}`);
  }
}

使用 extends 进行继承：

class Teacher extends Person {
  // …
}

方法

要定义方法，请使用方法定义语法：

const obj = {
  foo() {
    // …
  },
  bar() {
    // …
  },
};

而不是：

const obj = {
  foo: function () {
    // …
  },
  bar: function () {
    // …
  },
};

对象属性

Object.prototype.hasOwnProperty() 方法已被弃用，取而代之的是 Object.hasOwn()。

在可能的情况下，使用简写来避免属性标识符的重复。比如：

function createObject(name, age) {
  return { name, age };
}

不要这样写：

function createObject(name, age) {
  return { name: name, age: age };
}

运算符

本节列出了我们对使用哪些运算符以及何时使用的建议。

条件运算符

当你想要根据条件将一个字面量存储到变量中时，请使用条件（三元）运算符而不是 if...else 语句。此规则也适用于返回值时。比如：

const x = condition ? 1 : 2;

而不要这样：

let x;
if (condition) {
  x = 1;
} else {
  x = 2;
}

条件运算符在创建用来打印新信息的字符串时很有帮助。在这种情况下，使用常规的 if...else 语句会导致像打印日志这样的副操作变成长代码块，会混淆示例的重点。

严格相等运算符

优先使用严格相等（三等号）和不等运算符，而不是相等运算符（双等号）和不等运算符。

像这样使用严格相等和不等运算符：

name === "Shilpa";
age !== 25;

不要像下面这样使用宽松相等和不等运算符：

name == "Shilpa";
age != 25;

如果你需要使用 == 或 !=，请记住 == null 是唯一可接受的情况。由于 TypeScript 在所有其他情况下都会失败，因此我们不希望在示例代码中使用。考虑添加注释来解释你为什么需要它。

布尔值测试的简便方式

优先使用简便布尔值测试。例如，使用 if (x) 和 if (!x)，而不是 if (x === true) 和 if (x === false)，除非以不同的方式处理不同种类的真值或假值。

字符串

字符串字面量可以用单引号包含起来，比如 'A string'，也可以用双引号包含起来，比如 "A string"。不过，请不要在意需要选择使用哪个，Prettier 会保持一致。

模版字面量

要将值插入字符串，请使用模板字面量。

这里是一个推荐的使用模板字面量的例子。它们的使用可以防止大量的空格错误。

const name = "Shilpa";
console.log(`你好！我是 ${name}！`);

请不要像这样串联字符串：

const name = "Shilpa";
console.log("你好！我是 " + name + "！"); // 你好！我是 Shilpa！

请不要过度使用模版字面量。如果没有替换的话，请使用普通字符串。

变量

变量名称

好的变量名对理解代码至关重要。

使用简短的标识符，并避免不常用的缩写。好的变量名通常在 3 到 10 个字符之间，但这只是一个提示。例如，accelerometer 比为了字符长度而减短的缩写 acclmtr 更具描述性。
尝试使用现实世界相关的例子，其中每个变量都有清晰的语义。只有在示例简单且随意时才使用占位名称，比如 foo 和 bar。
不要使用匈牙利命名法命名约定。不要在变量名前面加上类型。比如，不要写成 bBought = oCar.sBuyer != null 或 sName = "John Doe"，而是写成 bought = car.buyer !== null 或 sName = "John Doe"。
对于集合，避免在命名中添加例如列表、数组、队列这样的类型名称。使用复数形式的内容名称。例如，对于汽车数组，使用 cars 而不是 carArray 或 carList。有时会有例外，比如你想在没有特定应用程序的上下文中展示一个特性的抽象形式。
对于原始值，使用小驼峰命名法，以小写字母开头。不要使用 _。在适当的情况下，使用简洁、可读性好且语义化的名称。比如，使用 currencyName 而不是 currency_name。
避免使用冠词和所有格，例如，使用 car 而不是 myCar 或 aCar。有时会有例外，比如你想在没有特定应用程序的上下文中展示一个特性的抽象形式。

使用变量名如下所示：

const playerScore = 0;
const speed = distance / time;

不要像这样命名变量：

const thisIsaveryLONGVariableThatRecordsPlayerscore345654 = 0;
const s = d / t;

备注： 唯一不允许使用可读性好的语义名称的地方是存在非常公认的惯例，例如将 i 和 j 用于循环迭代器。

变量声明

在声明变量和常量时，使用 let 和 const 关键字，而不是 var。下面的例子展示了 MDN Web 文档上推荐的和不推荐的用法：

如果一个变量不会被重新赋值，请使用 const，如下所示：
js
```
const name = "Shilpa";
console.log(name);
```
如果你会改变变量的值，请使用 let，如下所示：
js
```
let age = 40;
age++;
console.log("生日快乐！");
```
下面的示例在应该使用 const 的地方使用了 let，代码仍然可以运行，但我们希望在 MDN Web 文档代码示例中避免这种用法。
js
```
let name = "Shilpa";
console.log(name);
```
下面的示例使用 const 声明了一个变量，该变量会被重新赋值。重新赋值会抛出一个错误。
js
```
const age = 40;
age++;
console.log("生日快乐！");
```
下面的示例使用了 var，这会污染全局作用域：
js
```
var age = 40;
var name = "Shilpa";
```

一行声明一个变量，如下所示：

let var1;
let var2;
let var3 = "张三";
let var4 = var3;

不要在一行中通过逗号或链式声明来声明多个变量。避免像这样声明变量：

let var1, var2;
let var3 = var4 = "张三"; // var4 被隐式创建为全局变量；这在严格模式下会失败

强制类型转换

避免隐式强制类型转换。特别是，避免 +val 以强制将值转换未为数字，以及 "" + val 来将其强制转换为字符串。改为在不使用 new 的情况下使用 Number() 和 String()。例如：

class Person {
  #name;
  #birthYear;

  constructor(name, year) {
    this.#name = String(name);
    this.#birthYear = Number(year);
  }
}

不要这样写：

class Person {
  #name;
  #birthYear;

  constructor(name, year) {
    this.#name = "" + name;
    this.#birthYear = +year;
  }
}

要避免的 Web API

除了这些 JavaScript 语言特性之外，我们还建议你牢记一些与 Web API 相关的准则。

避免浏览器前缀

如果所有主流浏览器（Chrome、Edge、Firefox 和 Safari）都支持某个特性，请不要在该特性前面加上前缀。比如：

const context = new AudioContext();

避免增加前缀的复杂性，不要这样写：

const AudioContext = window.AudioContext || window.webkitAudioContext;
const context = new AudioContext();

同样的规则也适用于 CSS 前缀。

避免已弃用的 API

当一个方法、属性或一整个接口都已经弃用，不要使用它（除了它的文档）。相反，使用现代的 API。

以下是要避免的 Web API 以及用什么来替换它们的非详尽列表：

使用 fetch() 来替代 XHR（XMLHttpRequest）。
在 Web 音频 API 中使用 AudioWorklet 来替代 ScriptProcessorNode。

使用安全可靠的 API

请不要使用 Element.innerHTML 将纯文本内容插入到元素中；而是使用 Node.textContent 替代。innerHTML 属性可能会导致安全问题，如果开发人员不控制参数。作为编写者，我们越避免使用它，开发者复制和粘贴我们的代码时产生的安全漏洞就越少。下面的示例演示了 textContent 的用法。
js
```
const text = "父老乡亲们大家好";
const para = document.createElement("p");
para.textContent = text;
```
不要使用 innerHTML 将纯文本插入到 DOM 节点中。
js
```
const text = "父老乡亲们大家好";
const para = document.createElement("p");
para.innerHTML = text;
```
alert() 函数是不可靠的。在 MDN Web 文档，它在嵌入到 <iframe> 中的实时示例内无法正常工作。此外，它是对整个窗口的模态提示，这很令人讨厌。在静态代码示例中，使用 console.log() 或 console.error()。在实时示例中，避免使用 console.log() 和 console.error()，因为它们不会显示。而是使用专用的 UI 元素。

使用合适的打印方法

当打印一个消息时，使用 console.log()。
当打印一个错误时，使用 console.error()。

参见

JavaScript 参考——浏览我们的 JavaScript 参考页面，查看一些优秀、简洁、有意义的 JavaScript 代码片段。