Conceptos

Los conceptos son las cosas que un programador necesitaría entender para dominar un lenguaje. Los conceptos se enseñan mediante 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 del concepto, su slug y algo más.

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 y como se define en el archivo config.json.

Un concepto tiene dos tipos de archivos:

Archivos de documentación

Estos archivos se muestran al estudiante para ayudarle a entender el concepto.

  • about.md: ofrece información sobre el concepto a un estudiante que ya ha completado el ejercicio de concepto correspondiente, para que aprenda y pueda consultarla (obligatorio)
  • introduction.md: ofrece una breve introducción a un estudiante que todavía no ha completado 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 muestran al estudiante, sino que se usan para definir los metadatos del concepto.

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

Ejemplo

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

Archivo: about.md

Propósito: ofrecer información más detallada sobre el concepto a un estudiante que ya ha completado el ejercicio de concepto correspondiente, para que aprenda y pueda consultarla.

Presencia: obligatoria

Una vez completado 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 debería ofrecer al estudiante información completa sobre lo que necesita saber para dominar el concepto. Como mínimo, este archivo debe contener toda la información que se presenta en el documento introduction.md del concepto.

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

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

A continuación, algunos ejemplos de lo que se podría tratar.

  • Usos habituales de un concepto
  • Errores 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 tratan en otros conceptos (por ejemplo, el concepto recursión podría mencionar que el concepto 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 mismo archivo
  • Funcionalidades similares con las que se puede confundir el concepto
  • Características de rendimiento y uso de memoria, cuando son una consideración habitual 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. Por ejemplo, imagina un lenguaje que tiene algunas funcionalidades antiguas que los programadores con experiencia (y quizá incluso la documentación o las especificaciones oficiales) recomiendan no usar ya. Dar detalles sobre esas funcionalidades quedaría fuera del alcance del archivo about.md, porque no son relevantes para alcanzar la fluidez. No obstante, los mantenedores pueden optar por añadir un breve bloque para reconocer esos estándares antiguos si es probable que el estudiante se los encuentre con frecuencia en el mundo real. Eso sí, ese bloque debe marcarse como tal.

El archivo about.md DEBE estar claramente estructurado, sobre todo cuando contiene mucha información. En el futuro también habrá soporte para marcar partes como «temas avanzados» y así señalárselos 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: ofrecer una breve introducción a un estudiante que todavía no ha completado el ejercicio de concepto correspondiente.

Presencia: obligatoria

Este archivo se muestra si un estudiante todavía no ha completado el ejercicio de concepto correspondiente. Debería ofrecer una breve introducción al concepto.

  • Solo se debe incluir la información necesaria para entender los fundamentos del concepto. La información adicional debería reservarse 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 puede ser útil, en 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 adecuados para que el estudiante pueda buscar información adicional con facilidad.
  • Los ejemplos de código solo deben usarse para presentar sintaxis nueva (el estudiante no debería tener que buscar en la web ejemplos de sintaxis). En los demás casos, es preferible ofrecer 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: ofrecer enlaces útiles con más lecturas o información sobre un concepto.

Presencia: obligatoria

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

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 opcionalmente un campo icon_url, que permite personalizar el icono que se muestra al visualizar el enlace. Si no se especifica, el icono es el favicon por defecto.

[
  {
    "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 metainformación sobre el concepto.

Presencia: obligatoria

Este archivo contiene metainformación sobre el concepto:

  • authors: el nombre o los nombres de usuario de GitHub del autor o los autores del concepto (obligatorio)
    • Incluye también a los revisores si sus revisiones cambian sustancialmente el concepto (hasta el punto de que parece que «habéis llegado ahí juntos»)
  • contributors: el nombre o los nombres de usuario de GitHub del colaborador o los colaboradores del concepto (opcional)
    • Incluye también 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 a la vez autor y colaborador, inclúyelo únicamente 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 sentido.