编写代码示例的指南

代码示例的通用原则

您需要牢记一个最重要的考虑因素：读者会复制粘贴示例到他们自己的代码中，并可能将其投入生产。 因此，您应该确保代码示例是可用的，遵循普遍接受的最佳实践，并且不会导致应用程序出现不安全、效率低下、臃肿或不可访问的情况。

如果代码示例无法运行或不适用于生产环境，请在代码注释和解释性文本中包含警告；例如，如果它只是一个片段而不是完整的示例，请清楚地说明这一点。这也意味着您应该提供运行示例所需的所有信息，包括任何依赖项和设置信息。

代码示例应足够简洁易懂，但又足够复杂能做一些有趣且（最好是）有用的事情。其目的不一定是制作出能给专家留下深刻印象、功能强大且高效的代码，而是分享可以快速理解和学习的、简化的可运行示例。

一些更通用的指南包括

• 代码示例应简短，并且最好只展示您当前感兴趣的功能。
• 编写代码时，请尽可能使其易于理解，即使它不是最高效的写法。
• 不要包含不必要的服务器端代码、库、框架、预处理器和其他此类依赖项。它们会使代码更难移植，也更难运行和理解。尽可能使用原生代码。
• 不要假设读者了解任何库、框架、预处理器或其他非原生功能。例如，使用示例中具有意义的类名，而不是对于 BEM 或 Bootstrap 用户有意义的类名。
• 在代码示例中做到包容；请记住 MDN 的读者来自世界各地，并且在种族、宗教、年龄、性别等方面都多种多样。确保代码示例中的文本反映了这种多样性，并包容所有人。
• 不要为了简洁而使用已弃用的功能（例如 <big> 或 document.write() 等表示元素）；要正确使用。
• 对于 API 演示，如果您同时使用了多个 API，请指出其中包含了哪些 API，以及功能来自哪里。

浏览器支持

在为尚未在所有主要浏览器中都可用的技术创建代码示例时，请考虑使用 特性检测 来回退到更简单的行为，或告知用户他们的浏览器尚不支持。请勿在代码注释或文本中指定支持的浏览器及其版本，因为这些信息会很快过时。

MDN 代码风格和格式

关于正确缩进、空白和行长的意见一直存在争议。对这些主题的讨论会分散创建和维护内容的精力。在 MDN Web Docs 上，我们使用 Prettier 作为代码格式化工具，以保持代码风格的一致性并避免跑题的讨论。您可以查看我们的 配置文件 来了解当前规则，并阅读 Prettier 文档。

除了自动格式化之外，MDN 上的代码示例还有一些其他规则，以确保最终能得到良好的渲染。

选择正确的语言

为确保代码块的正确格式化和语法高亮，请正确指定代码块的语言。请参阅 MDN Markdown 中的示例代码块，了解 MDN 支持的语言列表以及如何请求新语言的详细信息。

如果代码块是伪代码、命令的输出，或者不是编程语言，请将语言设置为 plain

```plain
StaleElementReferenceException: The element reference of ABD-123 is stale…
```

代码行长度

代码行不应过长以至于需要水平滚动才能阅读。为了可读性，请在自然的断点处换行，但不要牺牲最佳实践。例如，这样并不好

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.`;

代码块高度

代码块应与所需长度相同，不多不少。理想情况下，目标是简短，例如 15-25 行。如果代码块会更长，可以考虑显示最有用的部分，并将完整的示例链接到 GitHub 仓库、Gist 或 CodePen 等地方。

行内代码格式化

使用行内代码语法来标记函数名、变量名和方法名。例如，“frenchText() 函数”在 markdown 中写为

the `frenchText()` function

方法名后面应跟一对括号：例如，doSomethingUseful()。括号有助于区分方法和其他代码术语。

正确渲染的指南

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

渲染的代码示例大小

• 宽度设置为 100%：MDN Web Docs 上的主内容区域在桌面上的宽度约为 700px，因此嵌入的代码示例必须在该宽度下看起来良好。
• 高度设置为低于 700px：我们建议将此高度用于渲染的代码示例宽度，以获得最佳的屏幕可读性。

突出显示好的或坏的示例

您会注意到在此页面上，代表良好实践的代码块在右角会显示绿色的对勾标记，而演示不良实践的代码块则显示红圈中的白色叉号。

您可以在编写代码示例时遵循相同的样式。您不必在所有地方都使用此样式 — 只需在您想专门强调代码示例中良好和不良用法的地方使用。

代码块使用 markdown 中的“代码围栏”来分隔代码块，后面跟信息字符串中的语言。例如

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

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

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

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

这些将渲染为

<p>Good example</p>

<p>Bad example</p>

占位符文本使用指南

使用从 lipsum.com 生成的 lorem-ipsum 占位符文本，或 Lorem ipsum VS Code 插件。标准的 lorem-ipsum 文本包含在我们的拼写检查器配置中，因此在 IDE 或代码审查期间的测试中不会被报告为拼写错误。使用一致的占位符文本使示例代码更易于审查，尤其是在重复出现时。它还有助于使示例清晰地用于说明目的，并避免因无关内容分散读者的注意力。