给代码示例添加注释

关于代码注释

代码注释通过描述代码示例的功能和原因，帮助解释较长的代码示例。注释会在两栏布局中显示在代码示例旁边，这样我们可以编写更长的注释而不会使代码本身难以阅读。我们仅对完整的代码示例添加注释，而不是片段。并非每个代码示例都需要代码注释，只有在明确需要时才使用。

代码注释可为多种受众提供帮助。通常，代码注释用于向新用户解释关键概念或向更有经验的用户说明特定选择。

对于新手用户，代码注释可以超越代码示例的高级概览，解释每行代码的作用，使其像有朋友或同事引导一样理解代码。

对于更有经验的用户，代码注释可以帮助他们理解代码示例并根据自己的需求进行定制。注释可以解释为何代码以特定方式编写，以确保基础概念清晰。

您可以在单篇文章中为多个代码示例添加注释，但请注意，每个注释都会增加文章的复杂度，并为使用屏幕阅读器的用户带来重复的导航任务。如果文章中有多个代码示例，请考虑是否可以合并为一个示例。

启用和添加代码注释

为文章指定 layout: inline 前置属性。
使用三个反引号创建代码示例。
在三个反引号后指定代码示例的语言，然后加上 annotate。例如，```yaml annotate 或 ```ruby annotate。
在代码示例中使用注释标签（#、//、<&#33--、%%）添加注释。必须使用与代码样本所在语言对应的注释标签。例如，YAML 使用 #，JavaScript 使用 //。
- 带注释的代码示例必须以单行注释开始。如果您不想为第一行代码添加注释，可以使用空白注释。
- 注释适用于从注释标签所在行的下一行起，到下一个注释标签或代码块结束为止的代码。

注释规则

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

不支持多行风格的注释，例如 /*。
代码注释起始符号与注释内容之间必须有空格。
- 使用： # comment
- 避免： #comment
要创建空白注释，只需插入一个没有后续文字的注释标签。如果示例的某些行不需要注释，空白注释会很有用。
以 #! 开头的字符串会在代码块中显示，而不被视为注释。
注释标签后的所有内容将使用 Markdown 解析。链接、版本信息及其他样式将如同在 Markdown 中编写一样渲染。
多个连续的注释将合并为单个注释。
不以注释标签开始且为空或仅包含空格的行将被忽略。
必须使用单行注释开始代码段。如果代码的第一行（或第一段）不需要注释，可以使用没有文字的注释标签创建空白注释。
对于 HTML 样式，在注释后应加入闭合标签 ，以保持语法高亮。

代码注释最佳实践

在代码块之前的介绍中阐明代码示例的整体目的，并使用注释解释具体代码行的作用及其原因。

在代码注释中以清晰为首要，尽量保持简短。人们会把代码示例作为自己工作的基础，因此注释应帮助读者理解示例的写法以及如何将其改编用于其他用途。

编写代码注释时要考虑受众，不要假设读者了解示例为何以特定方式编写。

注释可用于展示代码的预期结果，但整个代码示例的结果应以最能服务受众的方式呈现：可以放在代码示例的介绍中，或在示例后进行讨论。

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

带注释的代码示例示例

以下示例展示了渲染后的代码注释效果以及生成它们的原始代码。

渲染示例

以下代码示例展示了一个在 PR 打开时发布欢迎评论的工作流。

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 仓库的 “Actions” 选项卡中。

on:

on 关键字用于定义触发工作流运行的事件。

  pull_request:
    types: [opened]

添加 pull_request 事件，使工作流在每次创建拉取请求时自动运行。

permissions:
  pull-requests: write

修改授予 GITHUB_TOKEN 的默认权限。

jobs:
  build:
    name: Post welcome comment

在 jobs 键中定义一个 ID 为 build 的作业。

    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: $
```

本文内容