Anmerkungen zu Codebeispielen

Informationen zu Codeanmerkungen

Codeanmerkungen helfen dabei, längere Codebeispiele zu erläutern, indem sie beschreiben, welche Aufgaben ein Codebeispiel ausführt und warum es das tut. Die Anmerkungen werden neben dem Codebeispiel in einem Layout mit zwei Bereichen ausgegeben, sodass längere Anmerkungen geschrieben werden können, ohne dass der Code selbst schwer lesbar wird. Anmerkungen werden nur für vollständige Codebeispiele verfasst, nicht für Codeschnipsel. Codeanmerkungen sind nicht für jedes Codebeispiel erforderlich und sollten nur verwendet werden, wenn sie eindeutig benötigt werden.

Codeanmerkungen können für eine Vielzahl von Zielgruppen hilfreich sein. Häufig werden Codeanmerkungen verwendet, um neuen Benutzerinnen wichtige Konzepte zu erläutern oder erfahrenen Benutzerinnen verschiedene Auswahlmöglichkeiten vorzustellen.

Bei neuen Benutzer*innen sind Codeanmerkungen eine Möglichkeit, zusätzlich zur reinen Ansicht eines Codebeispiels zu erklären, was jede Codezeile tut, damit diese Personen den Code so verstehen können, als ob sie durch einen Freund oder eine Kollegin hindurchgeführt würden.

Erfahrenen Benutzer*innen können Codeanmerkungen dabei helfen, ein Codebeispiel zu verstehen und es dann an ihre spezifischen Anforderungen anzupassen. In Anmerkungen lässt sich erläutern, warum Code auf eine bestimmte Weise geschrieben wurde, um die Grundlagen klarzustellen.

Du kannst mehrere Codebeispiele in einem einzigen Artikel mit Anmerkungen versehen. Denk aber daran, dass jede Anmerkung die Komplexität eines Artikels erhöht und wiederholte Navigationsaufgaben für Personen hinzufügt, die Bildschirmsprachausgaben verwenden. Wenn du mehrere Codebeispiele in einem Artikel bereitstellen möchtest, solltest du überlegen, ob sie zu einem einzelnen Beispiel kombiniert werden können.

Aktivieren und Hinzufügen von Codeanmerkungen

1. Gib die Frontmattereigenschaft layout: inline für den Artikel an.
2. Erstelle ein Codebeispiel mit dreifachen Backticks (Graviszeichen).
3. Gib nach dem dreifachen Backtick eine Sprache für das Codebeispiel an, gefolgt von annotate. Zum Beispiel: ```yaml annotate oder ```ruby annotate.
4. Füge Anmerkungen innerhalb des Codebeispiels mithilfe von Kommentartags (#, //, <&#33--, %%) hinzu. Du musst das Kommentartag für die Sprache verwenden, in der das Codebeispiel geschrieben ist. Beispielsweise # für YAML und // für JavaScript.
   • Ein mit Anmerkungen versehenes Codebeispiel muss mit einer einzeiligen Anmerkung beginnen. Du kannst mit einer leeren Anmerkung beginnen, wenn du der ersten Codezeile keine Anmerkung hinzufügen möchtest.
   • Anmerkungen gelten für den Code ab der Zeile unterhalb des Kommentartags bis zum nächsten Kommentartag oder bis zum Ende des Codeblocks.

Regeln für Anmerkungen

Die folgenden Regeln gelten für alle Codeanmerkungen.

• Mehrzeilige Kommentare wie /* werden nicht unterstützt.
• Du kannst eine beliebige Anzahl von Leerzeichen einfügen, bevor das Kommentartag beginnt.
• Du kannst eine beliebige Anzahl von Leerzeichen einfügen, nachdem das Kommentartag endet.
• Um eine leere Anmerkung zu erstellen, füge ein Kommentartag ohne Text ein. Leere Anmerkungen sind nützlich, wenn für einige Zeilen eines Beispiels keine Anmerkungen erforderlich sind.
• Zeichenketten, die mit #! beginnen, werden im Codeblock wiedergegeben und nicht als Kommentare behandelt.
• Jeglicher Text nach dem Kommentartag wird mit Markdown analysiert. Links, Versionsinformationen und andere Formatierungen werden so ausgegeben, als wären sie in Markdown geschrieben.
• Mehrere aufeinander folgende Kommentare erzeugen eine einzelne Anmerkung.
• Zeilen, die nicht mit einem Kommentartag beginnen und leer sind oder nur Leerzeichen enthalten, werden ignoriert.
• Du musst den Codeabschnitt mit einer einzeiligen Kommentar starten. Wenn für die erste Zeile (oder den ersten Abschnitt) des Codes keine Anmerkung erforderlich ist, kannst du ein Kommentartag ohne Text verwenden, um eine leere Anmerkung zu erstellen.
• Im HTML-Format musst du nach deinen Anmerkungen das schließende Tag <!-- --> hinzufügen, damit die Syntaxmarkierung erhalten bleibt.

Best Practices bei Codeanmerkungen

Stelle den allgemeinen Zweck eines Codebeispiels mit einem einführenden Text vor dem Codeblock vor, und verwende Anmerkungen, um zu erläutern, was bestimmte Codezeilen tun und warum sie dies tun.

Der wichtigste Aspekt bei Codeanmerkungen ist die Klarheit. Versuche aber gleichzeitig, sie so kurz wie möglich zu halten. Benutzer*innen verwenden Codebeispiele als Grundlage für ihre eigene Arbeit, sodass Anmerkungen den Leuten helfen sollten, das Beispiel so zu verstehen, wie es geschrieben ist, und auch zu erfahren, wie sie das Beispiel für andere Verwendungszwecke anpassen können.

Denke beim Schreiben von Codeanmerkungen immer an deine Zielgruppe, und gehe nicht davon aus, dass die Benutzer*innen wissen, warum ein Beispiel auf eine bestimmte Weise geschrieben wurde.

Anmerkungen können verwendet werden, um die erwarteten Ergebnisse für die jeweiligen Codezeilen anzuzeigen. Die Ergebnisse für das gesamte Codebeispiel sollten aber auf die für die Zielgruppe am besten geeignete Weise gezeigt werden: entweder in der Einführung zum Codebeispiel oder im Anschluss an das Beispiel.

Wenn ein Codebeispiel geändert wird, musst du überprüfen, ob alle Anmerkungen noch gültig sind.

Beispiel für ein Codebeispiel mit Anmerkungen

Die folgenden Beispiele zeigen, wie die Ausgabe von Codeanmerkungen und der unformatierte Code aussehen, der sie erzeugt.

Ausgegebenes Beispiel

Das folgende Codebeispiel zeigt einen Workflow, der beim Öffnen eines Pull Requests einen Begrüßungskommentar postet.

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

Unformatiertes Codebeispiel

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