代码示例标注

关于代码标注

代码标注通过描述代码示例的作用和原因来帮助解释较长的代码示例。标注在代码示例旁边以双面板布局呈现，因此我们可以编写更长的标注，而不会使代码本身难以阅读。我们只对完整的代码示例进行标注，而不是代码片段。并非每个代码示例都需要代码标注，只有在明确需要时才应使用。

代码标注可以帮助各种类型的读者。代码标注通常用于向新用户解释关键概念，或向更有经验的用户解释具体的代码选择。

对于新用户，代码标注是一种超越代码示例的高级概述的方法，它解释了每一行代码的作用，以便用户可以像朋友或同事指导他们一样理解代码。

对于更有经验的用户，代码标注可以帮助他们理解代码示例并将其调整为他们的特定需求。标注可以解释为什么代码以某种方式编写，以便使基本原理清晰明了。

您可以在一篇文章中为多个代码示例添加标注，但请记住，每个标注都会增加文章的复杂性，并为使用屏幕阅读器的用户添加重复的导航任务。如果文章中有多个代码示例，请考虑是否可以将它们组合成一个示例。

启用和添加代码标注

为文章指定 `layout: inline` 前端内容属性。
使用三个反引号创建代码示例。
在三个反引号之后指定代码示例的语言，然后加上 `annotate`。例如，` ```yaml annotate` 或 ` ```ruby annotate`。
使用代码示例中的注释标记（`#`、`//`、`<!--`、`%%`）添加标注。必须使用代码示例所用语言的注释标记。例如，YAML 使用 `#`，JavaScript 使用 `//`。
- 带标注的代码示例必须以单行标注开头。如果您不想为代码的第一行添加标注，则可以使用空标注开头。
- 标注应用于注释标记下方的代码行到下一个注释标记或代码块末尾之间的代码。

标注规则

以下规则适用于所有代码标注。

不支持多行样式注释，例如 `/*`。
您可以在注释标记开始之前包含任意数量的空格。
您可以在注释标记结束之后包含任意数量的空格。
要创建空标注，请插入一个不带任何文本的注释标记。如果示例的某些行不需要标注，则空标注很有用。
以 `#!` 开头的字符串将在代码块中呈现，不会被视为注释。
注释标记后的任何内容都将使用 Markdown 解析。链接、版本控制和其他样式将像在 Markdown 中编写一样呈现。
多个连续的注释将创建一个标注。
不以注释标记开头且为空或仅包含空格的行将被忽略。
必须以单行注释开始代码部分。如果代码的第一行（或部分）不需要标注，则可以使用不带文本的注释标记创建空标注。
对于 HTML 样式，应在标注后包含一个结束标记 `` 以保持语法高亮显示。

代码标注最佳实践

在代码块之前用引言介绍代码示例的整体目的，并使用标注解释特定代码行的作用及其原因。

在编写代码标注时应优先考虑清晰度，同时尽量保持简洁。人们使用代码示例作为他们自己工作的基础，因此标注应帮助人们理解示例的编写方式以及如何将其调整用于其他用途。

编写代码标注时应考虑您的读者，不要假设人们会知道示例为何以某种方式编写。

标注可用于显示其标注的代码的预期结果，但整个代码示例的结果应以最能服务于读者的方式呈现：代码示例的引言或示例之后进行讨论。

如果更改了代码示例，请检查所有标注是否仍然有效。

带标注的代码示例

以下示例显示呈现的代码标注的外观及其创建它们的原始代码。

呈现的示例

以下代码示例显示了一个工作流程，该工作流程在打开拉取请求时在其上发布欢迎评论。

YAML

# The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
name: Post welcome comment
# The `on` keyword lets you define the events that trigger when the workflow is run.
on:
  # Add the `pull_request` event, so that the workflow runs automatically
  # every time a pull request is created.
  pull_request:
    types: [opened]
# Modifies the default permissions granted to `GITHUB_TOKEN`.
permissions:
  pull-requests: write
# Defines a job with the ID `build` that is stored within the `jobs` key.
jobs:
  build:
    name: Post welcome comment
    # Configures the operating system the job runs on.
    runs-on: ubuntu-latest
    # The `run` keyword tells the job to execute a command on the runner.
    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GH_TOKEN: $
          PR_URL: $

name: Post welcome comment

工作流程的名称，它将显示在 GitHub 存储库的“操作”选项卡中。

on:

on 关键字允许您定义触发工作流程运行的事件。

  pull_request:
    types: [opened]

添加 `pull_request` 事件，以便每次创建拉取请求时工作流程都会自动运行。

permissions:
  pull-requests: write

修改授予 `GITHUB_TOKEN` 的默认权限。

jobs:
  build:
    name: Post welcome comment

定义一个 ID 为 `build` 的作业，该作业存储在 `jobs` 键中。

    runs-on: ubuntu-latest

配置作业运行的操作系统。

    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GH_TOKEN: $
          PR_URL: $

run 关键字指示作业在运行程序上执行命令。

# The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
name: Post welcome comment
# The `on` keyword lets you define the events that trigger when the workflow is run.
on:
  # Add the `pull_request` event, so that the workflow runs automatically
  # every time a pull request is created.
  pull_request:
    types: [opened]
# Modifies the default permissions granted to `GITHUB_TOKEN`.
permissions:
  pull-requests: write
# Defines a job with the ID `build` that is stored within the `jobs` key.
jobs:
  build:
    name: Post welcome comment
    # Configures the operating system the job runs on.
    runs-on: ubuntu-latest
    # The `run` keyword tells the job to execute a command on the runner.
    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GH_TOKEN: $
          PR_URL: $

原始代码示例

The following code example shows a workflow that posts a welcome comment on a pull request when it is opened.

```yaml annotate
# The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
name: Post welcome comment
# The `on` keyword lets you define the events that trigger when the workflow is run.
on:
  # Add the `pull_request` event, so that the workflow runs automatically
  # every time a pull request is created.
  pull_request:
    types: [opened]
# Modifies the default permissions granted to `GITHUB_TOKEN`.
permissions:
  pull-requests: write
# Defines a job with the ID `build` that is stored within the `jobs` key.
jobs:
  build:
    name: Post welcome comment
    # Configures the operating system the job runs on.
    runs-on: ubuntu-latest
    # The `run` keyword tells the job to execute a command on the runner.
    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GH_TOKEN: $
          PR_URL: $
```

本文内容