代码示例的注释

关于代码注释

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

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

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

对于更有经验的用户来说，代码注释可以帮助他们理解代码示例，然后根据自己的特定需求进行调整。注释可以解释为什么代码以某种方式编写，以便基础知识清晰明了。

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

启用和添加代码注释

为文章指定layout: inline 前置 matter 属性。
使用三个反引号创建代码示例。
在三个反引号后指定代码示例的语言，然后是annotate。例如， ```yaml annotate 或 ```ruby annotate。
使用注释标签（#、//、<&#33--、%%）在代码示例中添加注释。您必须使用代码示例所用语言的注释标签。例如，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: $
```

本文档