Conceptos

Los conceptos son las cosas que un programador necesita entender para tener fluidez en un lenguaje. Los conceptos se enseñan mediante los ejercicios de concepto y se usan como requisitos previos para los ejercicios de concepto y de práctica. Los conceptos se colocan en un mapa de conceptos cuando se muestran al estudiante.

Metadatos

Los metadatos de un concepto se definen en la clave concepts del archivo config.json. Los metadatos definen el UUID, el slug y más cosas del concepto.

Ejemplo

{
  "concepts": [
    {
      "uuid": "b9a421b2-c5ff-4213-bd6d-b886da31ea0d",
      "slug": "numbers",
      "name": "Numbers"
    }
  ]
}

Archivos

Cada concepto tiene su propio directorio dentro del directorio concepts del track. El nombre del directorio del concepto debe coincidir con la propiedad slug del concepto, tal como se define en el archivo config.json.

Un concepto tiene dos tipos de archivos:

Archivos de documentación

Estos archivos se presentan al estudiante para ayudar a explicar el concepto.

  • about.md: brinda información sobre el concepto para que un estudiante que completó el ejercicio de concepto correspondiente pueda aprender y consultar más adelante (obligatorio)
  • introduction.md: brinda una breve introducción para un estudiante que aún no completó el ejercicio de concepto correspondiente (obligatorio)
  • links.json: ofrece enlaces útiles con más lecturas o información sobre un concepto (obligatorio)

Archivos de metadatos

Estos archivos no se presentan al estudiante, sino que se usan para definir los metadatos del concepto.

  • .meta/config.json: contiene información meta sobre el concepto (obligatorio)

Ejemplo

concepts
└── numbers
    ├── .meta
    |   └── config.json
    ├── about.md
    ├── introduction.md
    └── links.json

Archivo: about.md

Propósito: Brindar información más detallada sobre el concepto para que un estudiante que completó el ejercicio de concepto correspondiente pueda aprender y consultar más adelante.

Presencia: Obligatorio

Después de completar el ejercicio de concepto correspondiente (lo que también se conoce como «aprender» un concepto), la página del concepto mostrará el contenido del archivo about.md en lugar del archivo introduction.md. El archivo about.md debe brindar a los estudiantes información completa sobre lo que necesitan saber para tener fluidez en el concepto. Como mínimo, este archivo debe contener toda la información que se presenta en el documento introduction.md de los conceptos.

Si el concepto presenta sintaxis nueva, se deben incluir ejemplos de esa sintaxis. El estudiante no debería tener que seguir muchos enlaces para adquirir el conocimiento que el archivo intenta transmitir. En cambio, el about.md debe contener suficiente información para que se entienda dentro de su contexto.

El archivo about.md no se limita al alcance del ejercicio de concepto correspondiente. El contenido puede requerir conocimientos de otros conceptos que se presentarán más adelante. Si se mencionan otros conceptos, se debe enlazar a sus respectivas introducciones (consulta enlaces internos para más detalles).

Estos son algunos ejemplos de lo que podría cubrirse.

  • Usos populares de un concepto
  • Trampas comunes en el uso de un concepto (por ejemplo, no tener en cuenta la seguridad de hilos)
  • Limitaciones de uso que pueden sorprender al desarrollador desprevenido
  • Enfoques alternativos que se abordan en otros conceptos (por ejemplo, el concepto de recursión podría mencionar que el concepto de funciones de orden superior ofrece un enfoque alternativo para problemas similares)
  • Concesiones hechas para facilitar el aprendizaje o para adaptarse al entorno de Exercism, por ejemplo, varias clases en un solo archivo
  • Características similares con las que se puede confundir el concepto
  • Características de rendimiento y uso de memoria, cuando sean una consideración común en ese lenguaje
  • No menciones un ejercicio en el texto, ya que este archivo se muestra fuera del contexto de un ejercicio.

El objetivo del archivo about.md no es proporcionar un conjunto completo de información sobre el concepto. Como ejemplo, imagina un lenguaje que tiene algunas características antiguas que los programadores con experiencia (y quizás incluso la documentación o las especificaciones oficiales) recomiendan no usar más. Proporcionar detalles sobre esas características quedaría fuera del alcance del archivo about.md, porque no son relevantes para alcanzar la fluidez. Sin embargo, los mantenedores pueden optar por añadir un bloque corto para reconocer los estándares antiguos si es probable que un estudiante se los encuentre con frecuencia en la práctica. Eso sí, ese bloque debe marcarse como tal.

El archivo about.md DEBE tener una estructura clara, especialmente cuando contiene mucha información. En el futuro también habrá soporte para marcar partes como «temas avanzados» y así señalarlas a los estudiantes interesados sin sobrecargar a los demás.

Ejemplo

# About

There are two different kinds of numbers in Elixir - integers and floats.

Floats are numbers with one or more digits behind the decimal separator. They use the 64-bit double precision floating-point format.

```elixir
float = 3.45
# => 3.45
```

Elixir also supports the scientific notation for floats.

```elixir
1.25e-2
# => 0.0125
```

## Rounding errors

Floats are infamous for their rounding errors.

```elixir
0.1 + 0.2
# => 0.30000000000000004
```

However, those kind of errors are not specific to Elixir. They happen in all programming languages. This is because all data on our computers is stored and processed as binary code. In binary, only fractions whose denominator can be expressed as `2^n` (e.g. `1/4`, `3/8`, `5/16`) can be expressed exactly. Other fractions are expressed as estimations.

```elixir
# 3/4
Float.ratio(0.75)
# => {3, 4}

# 3/5
Float.ratio(0.6)
# => {5404319552844595, 9007199254740992}
```

You can learn more about this problem at [0.30000000000000004.com][0.30000000000000004.com]. The [Float Toy page][evanw.github.io-float-toy] has a nice, graphical explanation how a floating-point number's bits are converted to an actual floating-point value.

Archivo: introduction.md

Propósito: Brindar una breve introducción para un estudiante que aún no completó el ejercicio de concepto correspondiente.

Presencia: Obligatorio

Este archivo se muestra si un estudiante aún no completó el ejercicio de concepto correspondiente. Debe brindar una breve introducción al concepto.

  • Solo se debe incluir la información necesaria para entender los fundamentos del concepto. La información adicional debe dejarse para el documento about.md.
  • Los enlaces deben usarse con moderación, si acaso. Aunque un enlace que explique un tema complejo como la recursión podría ser útil, para la mayoría de los conceptos los enlaces aportarán más información de la necesaria, así que el objetivo debería ser explicar las cosas de forma concisa en el propio texto.
  • Se deben usar los términos técnicos correctos para que el estudiante pueda buscar fácilmente más información.
  • Los ejemplos de código solo deben usarse para presentar sintaxis nueva (los estudiantes no deberían tener que buscar en la web ejemplos de sintaxis). En otros casos, ofrece descripciones o enlaces en lugar de código.
  • No menciones un ejercicio en el texto, ya que este archivo se muestra fuera del contexto de un ejercicio.

Ejemplo

# Introduction

One of the key aspects of working with numbers in C# is the distinction between integers and floating-point numbers (numbers with zero or more digits after the decimal separator).

The two most commonly used numeric types in C# are `int` (a 32-bit integer) and `double` (a 64-bit floating-point number).

```csharp
int i = 123;
double d = 54.29;
```

Propósito: Proporcionar enlaces útiles con más lecturas o información sobre un concepto.

Presencia: Obligatorio

Pueden ser documentación oficial, un buen tutorial, etc. Estos enlaces no reemplazan los enlaces más contextuales dentro del archivo about.md de un concepto, sino que ofrecen un conjunto rápido de puntos de referencia generales para el estudiante.

Cada enlace debe contener los siguientes campos:

  • url: la URL a la que enlaza.
  • description: una descripción del enlace, que se muestra como el texto del enlace.

Los enlaces también pueden tener un campo icon_url opcional, que sirve para personalizar el icono que se muestra cuando se visualiza el enlace. Si no se especifica, el icono predeterminado es el favicon.

[
  {
    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/intro-to-csharp/numbers-in-csharp-local",
    "description": "Numbers in C#"
  },
  {
    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/integral-numeric-types",
    "description": "Integral numeric types",
    "icon_url": "http://test.org/icon.png"
  }
]

Archivo: .meta/config.json

Propósito: Contiene información meta sobre el concepto.

Presencia: Obligatorio

Este archivo contiene información meta sobre el concepto:

  • authors: el o los nombres de usuario de GitHub del autor o los autores del concepto (obligatorio)
    • Incluye a los revisores si sus revisiones cambian sustancialmente el concepto (hasta el punto de que parezca que «llegaron ahí juntos»)
  • contributors: el o los nombres de usuario de GitHub del colaborador o los colaboradores del concepto (opcional)
    • Incluye a los revisores si sus revisiones son significativas, accionables o se han aplicado.
  • blurb: una breve descripción de este concepto. Su longitud debe ser <= 350. Markdown no es compatible (obligatorio)

Si alguien es autor y colaborador a la vez, solo inclúyelo como autor.

Ejemplo

{
  "authors": ["FSharpForever"],
  "contributors": ["IWantToHelp"],
  "blurb": "F# has two types of numbers: integers and floating-point numbers."
}

Ten en cuenta que:

  • El orden de los autores y los colaboradores no es significativo y no tiene ningún significado.