编写代码示例的指南

本节介绍了创建易于理解的最小代码示例以演示特定功能或函数用法的最佳实践。

您添加到 MDN Web 文档的代码示例应

• 足够简单，易于理解，但
• 足够复杂，可以做一些有趣的事情，最好是有用的。

您需要牢记的一项首要考虑因素是：读者会将代码示例复制粘贴到他们自己的代码中，并可能将其投入生产。

因此，您应确保代码示例可用，遵循普遍接受的最佳实践，并且不做任何会导致应用程序不安全、效率低下、臃肿或无法访问的事情。如果代码示例不可运行或不适合生产环境，请务必在代码注释和解释性文本中添加警告；例如，如果它只是一个代码片段而不是完整的示例，请明确说明。这也意味着您应提供所有运行示例所需的信息，包括任何依赖项和设置信息。

代码示例应尽可能自包含且易于理解。目标不一定是编写出让专家印象深刻、功能强大的高效、巧妙的代码，而是编写出尽可能快地理解的简化的工作示例。

一些更通用的最佳实践包括

• 代码示例应简短，理想情况下只显示您立即感兴趣的功能。
• 只包含对示例必不可少的代码。大量的无关代码很容易分散读者注意力或让他们感到困惑。如果您想提供一个完整的、更长的示例，请将其放在我们的 GitHub 代码库（或 JSBin、Codepen 或类似工具）中，然后在示例的上方或下方提供完整版本的链接。
• 不要包含不必要的服务器端代码、库、框架、预处理器和其他此类依赖项。它们会降低代码的可移植性，并使代码更难运行和理解。尽可能使用原生代码。
• 不要假设读者了解任何库、框架、预处理器或其他非原生功能。例如，使用在示例中具有意义的类名，而不是对 BEM 或 Bootstrap 用户有意义的类名。
• 尽可能编写整洁易懂的代码，即使它不是编写代码的最有效方式。
• 在您的代码示例中要具有包容性；考虑到 MDN 的读者来自世界各地，并且在种族、宗教、年龄、性别等方面都具有多样性。确保代码示例中的文本反映这种多样性，并且对所有人具有包容性。
• 不要为了简洁而使用不良实践（例如 <big> 或 document.write() 等演示元素）；正确地执行它。
• 在 API 演示的情况下，如果您同时使用多个 API，请指出包含哪些 API 以及哪些功能来自哪里。

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

在 MDN Web 文档中，我们使用 Prettier 作为代码格式化程序，以保持代码风格的一致性（并避免无关的讨论）。您可以参考我们的 配置文件 以了解当前规则，并阅读 Prettier 文档。

Prettier 会格式化所有代码并保持风格的一致性。尽管如此，您仍需遵循一些额外的规则。

这些 MDN Web 文档格式化代码示例的指南也是您编码时的良好实践。

为了确保代码块的正确格式和语法高亮，作者必须指定他们正在编写的代码块的语言。请参阅 MDN Markdown 中的示例代码块，了解 MDN 支持的语言列表以及有关如何请求新语言的详细信息。

如果代码块是伪代码、命令的输出或其他非编程语言，请明确将语言设置为 plain。

• 代码行不应该太长，以至于需要水平滚动才能阅读。
• 作为推荐做法，将代码行长度保持在 80 个字符以内（对于 交互式示例，则为 64 个字符）。
• 为了可读性，在自然断点处换行，但不要以牺牲最佳实践为代价。

例如，这不太好

let tommyCat =
  "Said Tommy the Cat as he reeled back to clear whatever foreign matter may have nestled its way into his mighty throat. Many a fat alley rat had met its demise while staring point blank down the cavernous barrel of this awesome prowling machine.";

这更好，但有点别扭

const tommyCat =
  "Said Tommy the Cat as he reeled back to clear whatever foreign " +
  "matter may have nestled its way into his mighty throat. Many a fat alley rat " +
  "had met its demise while staring point blank down the cavernous barrel of " +
  "this awesome prowling machine.";

更好的方法是使用模板字面量

const tommyCat = `Said Tommy the Cat as he reeled back to clear whatever foreign
  matter may have nestled its way into his mighty throat. Many a fat alley rat
  had met its demise while staring point blank down the cavernous barrel of
  this awesome prowling machine.`;

if (
  obj.CONDITION ||
  obj.OTHER_CONDITION ||
  obj.SOME_OTHER_CONDITION ||
  obj.YET_ANOTHER_CONDITION
) {
  /* something */
}

const toolkitProfileService = Components.classes[
  "@mozilla.org/toolkit/profile-service;1"
].createInstance(Components.interfaces.nsIToolkitProfileService);

代码块应该尽可能长，但不要更长。理想情况下，目标是 15-25 行左右的短代码块。如果代码块要长得多，请考虑只显示最有用的代码片段，并将完整示例的链接放在 GitHub 代码库或 CodePen 上。

内联代码格式

使用内联代码语法 (`) 标记函数名、变量名和方法名。例如："frenchText() 函数"。

方法名后应紧跟一对圆括号：例如，doSomethingUseful()。圆括号有助于将方法与其他代码术语区分开来。

应遵循这些指南，以确保您编写的代码示例在 MDN Web 文档上正确显示。您还应考虑响应式，使编写代码示例也适用于移动设备。

• 将宽度设置为 100%：MDN Web 文档上的主要内容窗格在桌面上的宽度约为 700 像素，因此嵌入式代码示例必须在该宽度下看起来正常。
• 将高度设置为低于 700 像素：我们建议将渲染的代码示例宽度保持在该高度范围内，以最大限度地提高屏幕上的可读性。

• 使用关键字表示主要颜色和其他“基本”颜色，例如
  css

  color: black;
  color: white;
  color: red;
  

• 对于更复杂的颜色（包括半透明颜色），请使用 rgb()
  css

  color: rgb(0 0 0 / 50%);
  color: rgb(248 242 230);
  

• 对于十六进制颜色，请在相关情况下使用简短形式
  css

  color: #058ed9;
  color: #a39a92c1;
  color: #ff0;
  color: #fbfa;
  

  css

  color: #ffff00;
  color: #ffbbffaa;
  

您会注意到，在本页面上，代表要遵循的最佳实践的代码块在右上角用一个绿色的勾号渲染，而演示不良实践的代码块则用一个红色圆圈中的白色叉渲染。

您可以在编写代码示例时遵循相同的风格。您不需要在任何地方都使用这种风格——只在您希望在代码示例中特别指出良好和不良实践的页面上使用即可。

要获得这种渲染效果，请使用“代码围栏”来界定代码块，并在后面加上语言信息字符串。例如

function myFunc() {
  console.log("Hello!");
}

要将代码块表示为好或坏的示例，请在语言字符串后面添加example-good或example-bad，如下所示

```html example-good
<p></p>
```

```html example-bad
<p></p>
```

这些将被渲染为

<p class="brush: js example-good"></p>

<p class="brush: js example-bad"></p>