{"meta":{"title":"Exemples d’annotation de code","intro":"Vous pouvez annoter des exemples de code plus longs pour expliquer comment ils fonctionnent et comment les utilisateurs peuvent les personnaliser pour d’autres utilisations.","product":"Contribuer à GitHub Docs","breadcrumbs":[{"href":"/fr/contributing","title":"Contribuer à GitHub Docs"},{"href":"/fr/contributing/writing-for-github-docs","title":"Écriture pour GitHub Docs"},{"href":"/fr/contributing/writing-for-github-docs/annotating-code-examples","title":"Exemples d’annotation de code"}],"documentType":"article"},"body":"# Exemples d’annotation de code\n\nVous pouvez annoter des exemples de code plus longs pour expliquer comment ils fonctionnent et comment les utilisateurs peuvent les personnaliser pour d’autres utilisations.\n\n## À propos des annotations de code\n\nLes 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.\n\nLes 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.\n\nPour 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.\n\nPour 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.\n\nVous 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.\n\n## Activation et ajout d’annotations de code\n\n1. Spécifiez la propriété frontmatter `layout: inline` pour l’article.\n1. Créez un exemple de code à l’aide de trois apostrophes inverses.\n1. 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`.\n1. Ajoutez des annotations à l’aide d’étiquettes de commentaire (`#`, `//`, <code><&#33--</code>, `%%`) 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.\n   * 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.\n   * 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.\n\n### Règles d’annotation\n\nLes règles suivantes s’appliquent à toutes les annotations de code.\n\n* Les commentaires de style multiligne, tels que `/*` ne sont pas pris en charge.\n* Il doit y avoir un espace entre le symbole qui démarre une annotation de code et le commentaire.\n  * **Utiliser :**`# comment`\n  * **Éviter :**`#comment`\n* 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.\n* Les chaînes qui commencent par `#!` s’affichent dans le bloc de code et ne sont pas traitées comme des commentaires.\n* 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.\n* Plusieurs commentaires séquentiels créent une seule annotation.\n* Les lignes qui ne commencent pas par une étiquette de commentaire et qui sont vides ou contiennent uniquement des espaces sont ignorées.\n* 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.\n* Pour le style HTML, vous devez inclure une balise fermante, `<!-- -->`, après vos annotations pour conserver la mise en surbrillance de la syntaxe.\n\n## Meilleures pratiques en matière d’annotations de code\n\nPré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.\n\nDonnez 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.\n\nTenez 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.\n\nLes 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.\n\nSi un exemple de code est modifié, vérifiez que toutes les annotations sont toujours valides.\n\n## Exemple d’exemple de code annoté\n\nLes exemples suivants montrent à quoi ressemblent les annotations de code affichées et le code brut qui les crée.\n\n### Exemple affiché\n\nL’exemple de code suivant montre un workflow qui publie un commentaire de bienvenue sur une demande de tirage lors de son ouverture.\n\n```yaml annotate\n# The name of the workflow as it will appear in the \"Actions\" tab of the GitHub repository.\nname: Post welcome comment\n# The `on` keyword lets you define the events that trigger when the workflow is run.\non:\n  # Add the `pull_request` event, so that the workflow runs automatically\n  # every time a pull request is created.\n  pull_request:\n    types: [opened]\n# Modifies the default permissions granted to `GITHUB_TOKEN`.\npermissions:\n  pull-requests: write\n# Defines a job with the ID `build` that is stored within the `jobs` key.\njobs:\n  build:\n    name: Post welcome comment\n    # Configures the operating system the job runs on.\n    runs-on: ubuntu-latest\n    # The `run` keyword tells the job to execute a command on the runner.\n    steps:\n      - run: gh pr comment $PR_URL --body \"Welcome to the repository!\"\n        env:\n          GH_TOKEN: $\n          PR_URL: $\n```\n\n### Exemple de code brut\n\n    The following code example shows a workflow that posts a welcome comment on a pull request when it is opened.\n\n    ```yaml annotate\n    # The name of the workflow as it will appear in the \"Actions\" tab of the GitHub repository.\n    name: Post welcome comment\n    # The `on` keyword lets you define the events that trigger when the workflow is run.\n    on:\n      # Add the `pull_request` event, so that the workflow runs automatically\n      # every time a pull request is created.\n      pull_request:\n        types: [opened]\n    # Modifies the default permissions granted to `GITHUB_TOKEN`.\n    permissions:\n      pull-requests: write\n    # Defines a job with the ID `build` that is stored within the `jobs` key.\n    jobs:\n      build:\n        name: Post welcome comment\n        # Configures the operating system the job runs on.\n        runs-on: ubuntu-latest\n        # The `run` keyword tells the job to execute a command on the runner.\n        steps:\n          - run: gh pr comment $PR_URL --body \"Welcome to the repository!\"\n            env:\n              GH_TOKEN: $\n              PR_URL: $\n    ```"}