Anotación de ejemplos de código

Acerca de las anotaciones de código

Las anotaciones de código ayudan a explicar ejemplos de código más largos mediante la descripción de lo que hace un ejemplo de código y el motivo por lo que lo hace. Las anotaciones se representan junto al ejemplo de código en dos paneles, lo que permite que se puedan escribir anotaciones más largas sin dificultar la lectura del código. Solo anotamos ejemplos de código completos, no fragmentos de código. Las anotaciones de código no son necesarias para todos los ejemplos de código y solo deben usarse si hay una necesidad clara de ellas.

Las anotaciones de código pueden resultar útiles para una variedad de audiencias. A menudo, las anotaciones de código se usarán para explicar conceptos clave a nuevos usuarios u opciones concretas a usuarios más experimentados.

En el caso de los nuevos usuarios, las anotaciones de código son una forma de ir más allá de la visión general de alto nivel de un ejemplo de código y de explicar lo que hace cada línea de código, con el fin de que cualquiera pueda entender el código como si un amigo o compañero de trabajo le estuviera guiando a través de él.

En cuanto a los usuarios más experimentados, las anotaciones de código pueden ayudarles a conocer un ejemplo de código y, posteriormente, a adaptarlo a sus necesidades específicas. Las anotaciones pueden explicar los motivos por los que el código se ha escrito de una manera determinada, con el fin de que los aspectos básicos queden claros.

En un solo artículo se pueden anotar varios ejemplos de código, pero hay que tener en cuenta que cada anotación aumenta la complejidad de un artículo y agrega tareas de navegación repetitivas para las personas que usan lectores de pantalla. Si tienes varios ejemplos de código en un artículo, piensa si se pueden combinar para formar un solo ejemplo.

Habilitación y adición de anotaciones de código

1. Especifica la layout: inline propiedad frontmatter del artículo.
2. Crea un ejemplo de código mediante triples acentos graves.
3. Especifica el lenguaje del ejemplo de código después del triple acento grave, seguido de annotate. Por ejemplo, ```yaml annotate o ```ruby annotate.
4. Utiliza etiquetas de comentario (#, //, <&#33--, %%) en el ejemplo de código para agregar anotaciones. Debes usar la etiqueta de comentario para el lenguaje en el que está escrito el ejemplo de código. Por ejemplo, # para YAML y // para JavaScript.
   • Un ejemplo de código anotado debe comenzar con una anotación de línea. Si no quieres agregar una anotación a la primera línea de código, puedes empezar con una anotación en blanco.
   • Las anotaciones se aplican al código de la línea que se encuentra debajo de la etiqueta de comentario a la siguiente etiqueta de comentario o al final del bloque de código.

Reglas de anotación

Las siguientes reglas se aplican a todas las anotaciones de código.

• No se admiten comentarios multilínea, como /*.
• Antes de que se inicie la etiqueta de comentario se pueden incluir tantos espacios como se desee.
• Después de que finalice la etiqueta de comentario se pueden incluir tantos espacios como se desee.
• Para crear una anotación en blanco, inserte una etiqueta de comentario sin texto después. Las anotaciones en blanco son útiles si algunas líneas de un ejemplo no requieren anotación.
• Las cadenas que comienzan por #! se representarán en el bloque de código y no se tratarán como comentarios.
• Todos los elementos que haya después de la etiqueta de comentario se analizarán con Markdown. Tanto los vínculos, como el control de versiones y otros estilos se representarán como si estuvieran escritos en Markdown.
• Varios comentarios secuenciales crearán una anotación.
• Se omitirán las líneas que no comienzan con una etiqueta de comentario y que estén vacías o que solo contengan espacios.
• La sección de código debe comenzar con un comentario de línea. Si la primera línea (o sección) del código no necesita ninguna anotación, puedes usar una etiqueta de comentario sin texto para crear una anotación en blanco.
• Para el estilo HTML, debes incluir una etiqueta de cierre, <!-- -->, después de las anotaciones para mantener el resaltado de la sintaxis.

Procedimientos recomendados de anotaciones de código

Para especificar el propósito general de un ejemplo de código escribe introducción antes del bloque de código y usa anotaciones para explicar lo que hacen las líneas de código concretas y por qué lo hacen.

Da prioridad la claridad en las anotaciones de código, pero intenta que sean lo más cortas posible. Los ejemplos de código se usan como base para el trabajo, por lo que las anotaciones deben servir de ayuda para comprender el ejemplo tal como se escribe y para saber cómo adaptar el ejemplo para otros usos.

Ten en cuenta a la audiencia al escribir anotaciones de código y no des por sentado que se van a conocer los motivos por los que se escribe un ejemplo de una manera determinada.

Las anotaciones se pueden usar para mostrar los resultados que se esperan del código que anotan, pero los resultados de todo el ejemplo de código deben estar de la manera que mejor sirva al público: en la introducción del ejemplo de código o en lo que se describe después del ejemplo.

Si se cambia un ejemplo de código, comprueba que todas las anotaciones siguen siendo válidas.

Ejemplo de un ejemplo de código anotado

En los ejemplos siguientes se muestra el aspecto de las anotaciones de código representadas y el código sin formato que los crea.

Ejemplo representado

En el ejemplo de código siguiente se muestra un flujo de trabajo que publica un comentario de bienvenida en una solicitud de incorporación de cambios cuando se abre.

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

Ejemplo de código sin formato

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