批注代码示例

关于代码注释

代码注释通过描述代码示例的用途和原因来帮助解释较长的代码示例。 注释以两个窗格布局呈现在代码示例旁边，因此我们可以编写更长的批注，而不会使代码本身难以阅读。 我们只批注完整的代码示例，而不是代码片段。 代码注释并非每个代码示例都是必需的，仅当明确需要它们时才应使用。

代码注释对各种受众都很有用。 通常，代码注释将用于向新用户解释关键概念或向更有经验的用户解释特定选择。

对于新用户，代码注释是一种超越代码示例的简要概述并解释每行代码用途的方法，以便有人可以理解代码，就好像朋友或同事在引导他们完成代码一样。

对于更有经验的用户，代码注释可以帮助他们了解代码示例，然后根据他们的具体需求对其进行定制。 注释可以解释为什么以某种方式编写代码，以便了解基础知识。

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

启用和添加代码注释

1. 为项目指定 layout: inline 前辅文属性。
2. 使用三重反引号创建代码示例。
3. 在三重反引号后为代码示例指定一种语言，后跟 annotate。 例如， ```yaml annotate 或 ```ruby annotate。
4. 在代码示例中使用注释标记（#、//、<&#33--、%%）添加注释。 必须为编写代码示例时使用的语言使用注释标记。 例如，# 表示 YAML，// 表示 JavaScript。
   • 批注的代码示例必须以单行注释开头。 如果不想向第一行代码添加注释，可以从空白注释开始。
   • 注释应用于注释标记下方行到下一注释标记或代码块末尾的代码。

注释规则

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

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

代码注释最佳做法

通过代码块前的简介来介绍代码示例的总体用途，并使用注释来解释特定代码行的用途以及它们这样做的原因。

优先处理代码批注的清晰度，同时尝试尽量缩短代码注释。 用户使用代码示例作为其自己工作的基础，因此注释应帮助用户了解编写的示例，以及他们如何调整示例以用于其他用途。

编写代码注释时，请考虑受众，不要认为用户会知道以某种方式编写示例的原因。

注释可用于显示它们批注的代码的预期结果，但整个代码示例的结果应采用最适合受众的方式：代码示例的简介或在示例之后讨论。

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

批注的代码示例的示例

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

呈现的示例

以下代码示例展示了一个工作流，该工作流在打开拉取请求时对其发布欢迎注释。

# 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

on:

  pull_request:
    types: [opened]

permissions:
  pull-requests: write

jobs:
  build:
    name: Post welcome comment

    runs-on: ubuntu-latest

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

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