Примеры кода аннотирования

Сведения о заметках кода

Заметки кода помогают объяснить более длинные примеры кода, описывая, какой пример кода делает и почему. Заметки отрисовываются рядом с примером кода в макете двух панелей, поэтому мы можем писать более длинные заметки, не делая сам код сложным для чтения. Мы добавляем только полные примеры кода, а не фрагменты кода. Заметки кода не являются обязательными для каждого примера кода и должны использоваться только в том случае, если для них есть четкое требование.

Заметки кода могут быть полезны для различных аудиторий. Часто заметки кода будут использоваться для объяснения ключевых понятий новым пользователям или конкретным вариантам для более опытных пользователей.

Для новых пользователей заметки кода — это способ выйти за рамки высокого уровня примера кода и объяснить, что делает каждая строка кода, чтобы кто-то понимал код, как если бы друг или коллега направлял их через него.

Для более опытных пользователей заметки кода могут помочь им понять пример кода, а затем адаптировать его к конкретным потребностям. Заметки могут объяснить, почему код был написан определенным способом, чтобы основные принципы были понятны.

Вы можете запомнить несколько примеров кода в одной статье, но помните, что каждая заметка повышает сложность статьи и добавляет повторяющиеся задачи навигации для людей, использующих средства чтения с экрана. Если в статье есть несколько примеров кода, рассмотрите возможность их объединения в один пример.

Включение и добавление заметок кода

1. layout: inline Укажите свойство frontmatter для статьи.
2. Создайте пример кода с помощью тройных обратных наборов.
3. Укажите язык для примера кода после тройного обратного значения, за которым следует annotate. Например, ```yaml annotate или ```ruby annotate.
4. Добавьте заметки с помощью тегов комментариев (#, //, <&#33--, %%) в примере кода. Необходимо использовать тег комментария для языка, на который написан пример кода. Например, # для YAML и // JavaScript.
   • Пример кода с аннотированной строкой должен начинаться с одной строки заметки. Вы можете начать с пустой заметки, если вы не хотите добавить заметку в первую строку кода.
   • Заметки применяются к коду из строки под тегом комментария к следующему тегу комментариев или концу блока кода.

Правила заметки

Следующие правила применяются ко всем заметкам кода.

• Многостроковые комментарии, такие как /* не поддерживаются.
• Вы можете включить любое количество пробелов перед началом тега комментариев.
• Вы можете включить любое количество пробелов после окончания тега комментария.
• Чтобы создать пустую заметку, вставьте тег комментария без текста после него. Пустые заметки полезны, если некоторые строки примера не требуют заметки.
• Строки, которые начинаются с #! отрисовки в блоке кода и не рассматриваются как комментарии.
• Все, что после тега комментария будет проанализировано с Markdown. Ссылки, управление версиями и другие стили будут отображаться, как если бы они были написаны в Markdown.
• Несколько последовательных комментариев создают одну заметку.
• Строки, которые не начинаются с тега комментария и пусты или содержат пробелы, будут игнорироваться.
• Необходимо запустить раздел кода с одной строковый комментарий. Если первая строка (или раздел) кода не требует заметки, можно использовать тег комментария без текста для создания пустой заметки.
• Для стиля HTML следует включить закрывающий тег после <!-- -->заметок, чтобы поддерживать выделение синтаксиса.

Рекомендации по заметкам кода

Введите общую цель примера кода с введением перед блоком кода и используйте заметки, чтобы объяснить, какие строки кода делают и почему они делают это.

Приоритет ясности в заметках кода при попытке сохранить их как можно короче. Люди используют примеры кода в качестве основы для собственной работы, поэтому заметки должны помочь людям понять пример, как он написан, и как они могут адаптировать пример для других использования.

Учитывайте аудиторию при написании заметок кода и не предполагайте, что люди будут знать, почему пример написан определенным образом.

Заметки можно использовать для отображения ожидаемых результатов для кода, который они заметят, но результаты для всего примера кода должны быть в любом случае лучше всего служить аудитории: введение в пример кода или обсуждение после примера.

Если пример кода изменен, убедитесь, что все заметки по-прежнему допустимы.

Пример примера аннотированного кода

В следующих примерах показано, как выглядят отрисованные заметки кода и создаваемый им необработанный код.

Пример отрисовки

В следующем примере кода показан рабочий процесс, который публикует приветственный комментарий к запросу на вытягивание при открытии.

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

Пример необработанного кода

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