Exemples d’annotation de code

À propos des annotations de code

Les annotations de code permettent d’expliquer des exemples de code plus longs en décrivant ce que fait un exemple de code et pourquoi. Les annotations s’affichent en regard de l’exemple de code dans une disposition à deux volets, ce qui nous permet d’écrire des annotations plus longues sans rendre le code lui-même difficile à lire. Nous annotons uniquement des exemples de code complets, pas des extraits de code. Les annotations de code ne sont pas requises pour chaque exemple de code et ne doivent être utilisées que si elles sont clairement nécessaires.

Les annotations de code peuvent être utiles pour diverses audiences. Souvent, les annotations de code sont utilisées pour expliquer les concepts clés aux nouveaux utilisateurs ou des choix spécifiques à des utilisateurs plus expérimentés.

Pour les nouveaux utilisateurs, les annotations de code sont un moyen d’aller au-delà de la vue d’ensemble générale d’un exemple de code et d’expliquer ce que fait chaque ligne de code afin que quelqu’un puisse comprendre le code comme si un ami ou un collègue les guidait à travers celui-ci.

Pour les utilisateurs plus expérimentés, les annotations de code peuvent les aider à comprendre un exemple de code, puis à l’adapter à leurs besoins spécifiques. Les annotations peuvent expliquer pourquoi le code a été écrit d’une certaine façon afin que les principes de base soient clairs.

Vous pouvez annoter plusieurs exemples de code dans un seul article, mais gardez à l’esprit que chaque annotation augmente la complexité d’un article et ajoute des tâches de navigation répétitives pour les personnes utilisant des lecteurs d’écran. Si vous avez plusieurs exemples de code dans un article, déterminez s’ils peuvent être combinés en un seul exemple.

Activation et ajout d’annotations de code

Spécifiez la propriété frontmatter layout: inline pour l’article.
Créez un exemple de code à l’aide de trois apostrophes inverses.
Spécifiez un langage pour l’exemple de code après les trois apostrophes inverses, suivi de annotate. Par exemple, ```yaml annotate ou ```ruby annotate.
Ajoutez des annotations à l’aide d’étiquettes de commentaire (#, //, <&#33--, %%) dans l’exemple de code. Vous devez utiliser l’étiquette de commentaire pour le langage dans lequel l’exemple de code est écrit. Par exemple, # pour YAML et // pour JavaScript.
- Un exemple de code annoté doit commencer par une annotation de ligne unique. Vous pouvez commencer par une annotation vide si vous ne souhaitez pas ajouter d’annotation à la première ligne de code.
- Les annotations s’appliquent au code de la ligne sous l’étiquette de commentaire à l’étiquette de commentaire suivante ou à la fin du bloc de code.

Règles d’annotation

Les règles suivantes s’appliquent à toutes les annotations de code.

Les commentaires de style multiligne, tels que /* ne sont pas pris en charge.
Vous pouvez inclure n’importe quel nombre d’espaces avant le commencement de l’étiquette de commentaire.
Vous pouvez inclure n’importe quel nombre d’espaces avant la fin de l’étiquette de commentaire.
Pour créer une annotation vide, insérez une étiquette de commentaire sans texte après celle-ci. Les annotations vides sont utiles si certaines lignes d’un exemple ne nécessitent pas d’annotation.
Les chaînes qui commencent par #! s’affichent dans le bloc de code et ne sont pas traitées comme des commentaires.
Tout ce qui se trouve après l’étiquette de commentaire sera analysé avec Markdown. Les liens, contrôles de version et autres styles s’affichent comme s’ils étaient écrits dans Markdown.
Plusieurs commentaires séquentiels créent une seule annotation.
Les lignes qui ne commencent pas par une étiquette de commentaire et qui sont vides ou contiennent uniquement des espaces sont ignorées.
Vous devez démarrer la section de code avec un commentaire d’une seule ligne. Si la première ligne (ou section) du code n’a pas besoin d’annotation, vous pouvez utiliser une étiquette de commentaire sans texte pour créer une annotation vide.
Pour le style HTML, vous devez inclure une balise fermante, ``, après vos annotations pour conserver la mise en surbrillance de la syntaxe.

Meilleures pratiques en matière d’annotations de code

Présentez l’objectif global d’un exemple de code avec une introduction avant le bloc de code et utilisez des annotations pour expliquer ce que font des lignes de code spécifiques et pourquoi elles le font.

Donnez la priorité à la clarté dans les annotations de code tout en essayant de les garder aussi courtes que possible. Les exemples de code sont utilisés par les utilisateurs comme base pour leur propre travail. Les annotations doivent donc les aider à comprendre l’exemple tel qu’il est écrit et comment ils peuvent adapter l’exemple à d’autres utilisations.

Tenez compte de votre public lors de l’écriture d’annotations de code et ne supposez pas que les utilisateurs sauront pourquoi un exemple est écrit d’une certaine façon.

Les annotations peuvent être utilisées pour afficher les résultats attendus pour le code qu’elles annotent, mais les résultats de l’exemple de code entier doivent correspondre à la manière la mieux adaptée à l’audience : présentation de l’exemple de code ou discussion après l’exemple.

Si un exemple de code est modifié, vérifiez que toutes les annotations sont toujours valides.

Exemple d’exemple de code annoté

Les exemples suivants montrent à quoi ressemblent les annotations de code affichées et le code brut qui les crée.

Exemple affiché

L’exemple de code suivant montre un workflow qui publie un commentaire de bienvenue sur une demande de tirage lors de son ouverture.

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

Exemple de code brut

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