Anotar exemplos de código

Sobre as anotações de código

As anotações de código ajudam a explicar exemplos de código mais longos descrevendo o que eles fazem e por quê. As anotações são renderizadas ao lado do exemplo de código em um layout de dois painéis. Assim, podemos escrever anotações mais longas sem dificultar a leitura do próprio código. Anotamos apenas exemplos de código completos, não trechos. As anotações de código não são necessárias para cada exemplo de código e devem ser usadas apenas se houver uma necessidade clara de usá-las.

As anotações de código podem ser úteis para uma variedade de públicos. Frequentemente, as anotações de código serão usadas para explicar conceitos-chave para novos usuários ou escolhas específicas para usuários mais experientes.

Para novos usuários, as anotações de código são uma maneira de ter uma visão geral de alto nível ainda mais abrangente de um exemplo de código e explicar o que cada linha de código faz para que as pessoas possam entender o código como se um amigo ou colega de trabalho o estivesse explicando.

Para usuários mais experientes, as anotações de código ajudam a entender um exemplo de código e adaptá-lo a necessidades específicas. As anotações podem explicar por que o código foi escrito de uma determinada maneira para que os conceitos básicos estejam claros.

Você pode anotar vários exemplos de código em um único artigo, mas lembre-se de que cada anotação aumenta a complexidade de um artigo e adiciona tarefas de navegação repetitivas para pessoas que usam leitores de tela. Se você tiver vários exemplos de código em um artigo, considere se eles podem ser combinados em um único exemplo.

Habilitar e adicionar anotações de código

1. Especifique a propriedade frontmatter layout: inline para o artigo.
2. Crie um exemplo de código usando aspas triplas.
3. Especifique uma linguagem do exemplo de código após as aspas triplas, seguido por annotate. Por exemplo, ```yaml annotate ou ```ruby annotate.
4. Adicione anotações usando marcas de comentário (#, //, <&#33--, %%) no exemplo de código. Você deve usar a marca de comentário para a linguagem em que o exemplo de código foi escrito. Por exemplo, # para YAML e // para JavaScript.
   • Um exemplo de código anotado deve começar com uma anotação de linha única. Você pode começar com uma anotação em branco se não quiser adicionar uma anotação à primeira linha de código.
   • As anotações se aplicam ao código da linha abaixo da marca de comentário até a próxima marca de comentário ou o final do bloco de código.

Regras de anotação

As regras a seguir se aplicam a todas as anotações de código.

• Não há suporte para comentários de estilo multilinha, como /*.
• Você pode incluir qualquer número de espaços antes do início da marca de comentário.
• Você pode incluir qualquer número de espaços após o término da marca de comentário.
• Para criar uma anotação em branco, insira uma marca de comentário sem texto após ela. Anotações em branco serão úteis se algumas linhas de um exemplo não exigirem uma anotação.
• As cadeias de caracteres que começam com #! serão renderizadas no bloco de código e não serão tratadas como comentários.
• Qualquer item após a marca de comentário será analisado com Markdown. Links, controle de versão e outros estilos serão renderizados como se tivessem sido escritos em Markdown.
• Vários comentários sequenciais criarão uma única anotação.
• As linhas que não começarem com uma marca de comentário e estiverem vazias ou contiverem apenas espaços serão ignoradas.
• Você deve iniciar a seção de código com um único comentário em linha. Se a primeira linha (ou seção) do código não precisar de uma anotação, você poderá usar uma marca de comentário sem texto para criar uma anotação em branco.
• No caso do estilo HTML, você deve incluir uma marca de fechamento, <!-- -->, após as anotações para manter o realce da sintaxe.

Melhores práticas de anotações de código

Apresente o objetivo geral de um exemplo de código com uma introdução antes do bloco de código e use anotações para explicar o que linhas específicas de código fazem e por que o fazem.

Priorize a clareza nas anotações de código enquanto tenta mantê-las o mais curtas possível. As pessoas usam exemplos de código como base para seu próprio trabalho, portanto, as anotações devem ajudá-las a entender o exemplo como está escrito e como elas podem adaptar o exemplo para outros usos.

Considere seu público ao escrever anotações de código e não pressuponha que as pessoas saberão por que um exemplo foi escrito de determinada maneira.

As anotações podem ser usadas para mostrar os resultados esperados do código anotado, mas os resultados para todo o exemplo de código devem atender à maneira que melhor satisfaz as necessidades do público: a introdução do exemplo de código ou discutido após o exemplo.

Se um exemplo de código for alterado, verifique se todas as anotações ainda estão válidas.

Amostra de um exemplo de código anotado

Os exemplos a seguir mostram como são as anotações de código renderizadas e o código bruto que as cria.

Exemplo renderizado

O exemplo de código a seguir mostra um fluxo de trabalho que publica um comentário de boas-vindas em uma solicitação de pull quando ela é aberta.

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

Exemplo de código bruto

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