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

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

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

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

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

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

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

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

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

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

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

• Многостроковые комментарии, такие как /* не поддерживаются.
• Между символом, который запускает заметку кода и комментарий, должно быть пробел.
  • Использование: # comment
  • Избегать: #comment
• Чтобы создать пустую заметку, вставьте тег комментария без текста после него. Пустые заметки полезны, если некоторые строки примера не требуют заметки.
• Строки, которые начинаются с #! отрисовки в блоке кода и не рассматриваются как комментарии.
• Все, что после тега комментария будет проанализировано с 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: $
```