コード例に注釈を付ける

コードの注釈について

コードの注釈でコード例の実行内容とその理由を説明することで、長いコード例をわかりやすくすることができます。 2 ペインのレイアウトで、コード例の横に注釈がレンダリングされます。そのため、長い注釈を書いてもコード自体は読みにくくなりません。スニペットではなく、完全なコード例にのみ注釈を付けます。コードの注釈はすべてのコード例に必須ではありません。明らかに必要な場合にのみ使ってください。

コードの注釈はさまざまな読み手に役立ちます。多くの場合、新しいユーザーには重要な概念を、経験豊富なユーザーには具体的な選択肢を説明するときにコードの注釈が使われます。

新しいユーザーの場合、コードの注釈によって、コード例の概要にとどまらず、友人や同僚から指導を受けているかのように各コード行の実行内容を理解できます。

経験豊富なユーザーの場合、コードの注釈はコード例を理解し、自分のニーズに合わせて調整するのに役立ちます。コードを特定の方法で記述した理由を注釈で説明し、原理を明確にすることができます。

1 つの記事で複数のコード例に注釈を付けることができますが、注釈を付けるたびに記事の複雑さが増し、スクリーンリーダーを使うユーザーにとっては反復的なナビゲーションタスクが追加されることに注意してください。 1 つの記事に複数のコード例がある場合は、それらを 1 つの例にまとめることができるかどうかを検討してください。

コードの注釈の有効化と追加

記事の layout: inline frontmatter プロパティを指定します。
3 つのバッククォートを使ってコード例を作成します。
コード例の言語を指定するには、3 つのバッククォートの後に annotate を続けます。たとえば、 ```yaml annotate または ```ruby annotate です。
コード例内にコメントタグ (#、//、<&#33--、%%) を使って注釈を追加します。コードサンプルを記述した言語のコメントタグを使う必要があります。たとえば、YAML の場合は#、JavaScript の場合は // です。
- 注釈を付けたコード例は、1 行の注釈で始める必要があります。コードの先頭行に注釈を追加したくない場合は、空の注釈で始めることができます。
- 注釈は、コメントタグの下の行から、次のコメントタグまたはコードブロックの末尾までのコード行に適用されます。

注釈の規則

次の規則は、すべてのコードの注釈に適用されます。

/* などの複数行スタイルのコメントはサポートされていません。
コメントタグの開始前には任意の数のスペースを入力できます。
コメントタグの終了後には任意の数のスペースを入力できます。
空の注釈を作成するには、後ろにテキストを入力せずにコメントタグを挿入します。空の注釈は、サンプルの一部の行に注釈が不要な場合に便利です。
先頭 #! の文字列はコードブロックにレンダリングされ、コメントとして扱われません。
コメントタグの後にあるものはすべて Markdown で解析されます。リンク、バージョン管理、その他のスタイル設定は、Markdown で記述されたかのようにレンダリングされます。
複数の連続するコメントで 1 つの注釈が作成されます。
コメントタグで始まらず、空であるかスペースのみを含む行は無視されます。
コードセクションは 1 行のコメントで始める必要があります。コード行の先頭行 (またはセクション) に注釈が必要ない場合は、テキストを含まないコメントタグを使って空の注釈を作成できます。
HTML スタイルの場合、構文の強調表示を維持するために注釈の後に閉じタグ  を含める必要があります。

コードの注釈のベストプラクティス

コードブロックの前に導入部を置いてコード例の全体的な目的を紹介し、注釈を使って各コード行の実行内容とその理由を説明します。

コードの注釈はわかりやすさを優先すると同時に、できるだけ短くするように心がけます。ユーザーは作業の基礎としてコードサンプルを使うので、注釈を参考にしてサンプルの記述内容と他の用途に合わせて調整する方法を理解できるようにします。

コードの注釈を記述するときは読み手を考慮し、例を特定の方法で記述した理由を誰でもわかると想定しないでください。

注釈を使うと、注釈を付けたコードに想定される結果を示すことができます。ただし、コード例全体の結果は、コード例の導入部または例の後で説明するなど、読み手にとって最適な方法で示す必要があります。

コード例を変更した場合は、すべての注釈が引き続き有効であることを確認します。

注釈付きコード例の例

次の例は、レンダリングされたコードの注釈がどのように表示されるか、またそれらを作成する生のコードを示しています。

レンダリングされた例

次のコード例は、pull request が開かれたときにウェルカムコメントを投稿するワークフローを示しています。

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

The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.

on:

The on keyword lets you define the events that trigger when the workflow is run.

  pull_request:
    types: [opened]

Add the pull_request event, so that the workflow runs automatically every time a pull request is created.

permissions:
  pull-requests: write

Modifies the default permissions granted to GITHUB_TOKEN.

jobs:
  build:
    name: Post welcome comment

Defines a job with the ID build that is stored within the jobs key.

    runs-on: ubuntu-latest

Configures the operating system the job runs on.

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

The run keyword tells the job to execute a command on the runner.

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