Concepts

Les concepts sont les éléments qu'un programmeur doit comprendre pour maîtriser un langage. Les concepts sont enseignés par les exercices d'apprentissage et servent de prérequis pour les exercices d'apprentissage et d'entraînement. Les concepts sont placés sur une carte des concepts lorsqu'ils sont présentés à l'apprenant.

Métadonnées

Les métadonnées d'un concept sont définies dans la clé concepts du fichier config.json. Ces métadonnées définissent l'UUID, le slug et d'autres informations du concept.

Exemple

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

Fichiers

Chaque concept a son propre dossier dans le dossier concepts du parcours. Le nom du dossier d'un concept doit correspondre à la propriété slug du concept, telle que définie dans le fichier config.json.

Un concept comporte deux types de fichiers :

Fichiers de documentation

Ces fichiers sont présentés à l'apprenant pour l'aider à comprendre le concept.

  • about.md : présente des informations sur le concept à un apprenant qui a terminé l'exercice d'apprentissage correspondant, afin qu'il puisse s'en servir et s'y référer plus tard (obligatoire)
  • introduction.md : présente une brève introduction à un apprenant qui n'a pas encore terminé l'exercice d'apprentissage correspondant (obligatoire)
  • links.json : fournit des liens utiles pour approfondir ou compléter ses connaissances sur un concept (obligatoire)

Fichiers de métadonnées

Ces fichiers ne sont pas présentés à l'apprenant, mais servent à définir les métadonnées du concept.

  • .meta/config.json : contient les méta-informations du concept (obligatoire)

Exemple

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

Fichier : about.md

Objectif : fournir des informations plus détaillées sur le concept à un apprenant qui a terminé l'exercice d'apprentissage correspondant, afin qu'il puisse les consulter et s'y référer.

Présence : obligatoire

Une fois l'exercice d'apprentissage correspondant terminé (ce qu'on appelle aussi « apprendre » un concept), la page du concept affiche le contenu du fichier about.md au lieu de celui du fichier introduction.md. Le fichier about.md doit fournir aux apprenants des informations complètes sur ce qu'ils doivent savoir pour maîtriser le concept. Ce fichier doit au minimum contenir toutes les informations présentées dans le document introduction.md du concept.

Si le concept introduit une nouvelle syntaxe, des exemples de cette syntaxe doivent y figurer. L'apprenant ne doit pas avoir à suivre une multitude de liens pour acquérir les connaissances que le fichier cherche à transmettre. Le fichier about.md doit au contraire contenir assez d'informations pour être compréhensible dans son contexte.

Le fichier about.md n'est pas limité au périmètre de l'exercice d'apprentissage correspondant. Son contenu peut nécessiter la connaissance d'autres concepts qui seront présentés plus tard. Si d'autres concepts sont mentionnés, il convient de renvoyer vers leurs introductions respectives (voir liens internes pour plus de détails).

Voici quelques exemples de ce qui peut être abordé.

  • les usages courants d'un concept
  • les pièges fréquents liés à l'usage d'un concept (par exemple, négliger la sûreté des threads)
  • les limites d'utilisation qui peuvent surprendre le développeur non averti
  • les approches alternatives traitées dans d'autres concepts (par exemple, le concept récursion peut mentionner que le concept fonctions d'ordre supérieur propose une approche différente de problèmes similaires)
  • les compromis faits pour faciliter l'apprentissage ou pour s'adapter à l'environnement Exercism, par exemple plusieurs classes dans un seul fichier
  • les fonctionnalités similaires avec lesquelles on peut confondre le concept
  • les caractéristiques de performance et la consommation de mémoire, lorsqu'il s'agit d'une préoccupation courante dans ce langage
  • ne pas faire référence à un exercice dans le texte, car ce fichier est affiché en dehors du contexte d'un exercice.

Le fichier about.md n'a pas pour but de fournir un ensemble complet d'informations sur le concept. Par exemple, imagine un langage qui possède d'anciennes fonctionnalités dont les programmeurs expérimentés (et parfois même la documentation ou les spécifications officielles) recommandent de ne plus se servir. Décrire ces fonctionnalités en détail sortirait du périmètre du fichier about.md, car elles ne sont pas utiles pour gagner en maîtrise. Les mainteneurs peuvent toutefois choisir d'ajouter un court paragraphe pour mentionner ces anciens standards si l'apprenant risque de les rencontrer couramment dans la nature. Ce paragraphe doit alors être clairement identifié comme tel.

Le fichier about.md DOIT être clairement structuré, surtout lorsqu'il contient beaucoup d'informations. À l'avenir, il sera aussi possible de marquer certaines parties comme « sujets avancés », afin de les signaler aux apprenants intéressés sans surcharger les autres.

Exemple

# 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.

Fichier : introduction.md

Objectif : fournir une brève introduction à un apprenant qui n'a pas encore terminé l'exercice d'apprentissage correspondant.

Présence : obligatoire

Ce fichier est affiché tant qu'un apprenant n'a pas encore terminé l'exercice d'apprentissage correspondant. Il doit présenter brièvement le concept.

  • ne fournir que les informations nécessaires pour comprendre les fondements du concept. Les informations supplémentaires ont leur place dans le document about.md.
  • utiliser les liens avec parcimonie, voire pas du tout. Un lien qui explique un sujet complexe comme la récursion peut être utile, mais pour la plupart des concepts, les liens apportent plus d'informations que nécessaire : l'objectif doit donc être d'expliquer les choses de façon concise directement dans le texte.
  • employer les termes techniques exacts, afin que l'apprenant puisse facilement rechercher davantage d'informations.
  • n'utiliser des exemples de code que pour introduire une nouvelle syntaxe (l'apprenant ne doit pas avoir à chercher des exemples de syntaxe sur le web). Dans les autres cas, préférer des descriptions ou des liens au code.
  • ne pas faire référence à un exercice dans le texte, car ce fichier est affiché en dehors du contexte d'un exercice.

Exemple

# 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;
```

Objectif : fournir des liens utiles pour approfondir ou compléter ses connaissances sur un concept.

Présence : obligatoire

Il peut s'agir de documentation officielle, d'un bon tutoriel, etc. Ces liens ne remplacent pas les liens plus contextuels du fichier about.md d'un concept, mais offrent à l'apprenant un ensemble de références générales faciles à consulter.

Chaque lien doit contenir les champs suivants :

  • url : l'URL vers laquelle le lien pointe.
  • description : une description du lien, affichée comme texte du lien.

Les liens peuvent aussi comporter un champ facultatif icon_url, qui permet de personnaliser l'icône affichée avec le lien. S'il n'est pas renseigné, l'icône utilisée est par défaut le 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"
  }
]

Fichier : .meta/config.json

Objectif : contient les méta-informations du concept.

Présence : obligatoire

Ce fichier contient les méta-informations du concept :

  • authors : le ou les noms d'utilisateur GitHub de l'auteur ou des auteurs du concept (obligatoire)
    • Y compris les relecteurs si leurs retours modifient substantiellement le concept (au point qu'on ait l'impression d'y être arrivé ensemble)
  • contributors : le ou les noms d'utilisateur GitHub du ou des contributeurs du concept (facultatif)
    • Y compris les relecteurs dont les retours sont pertinents, exploitables et pris en compte.
  • blurb : une brève description de ce concept. Sa longueur doit être inférieure ou égale à 350. Le Markdown n'est pas pris en charge (obligatoire)

Si quelqu'un est à la fois auteur et contributeur, ne l'indiquer que comme auteur.

Exemple

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

À noter :

  • L'ordre des auteurs et des contributeurs n'a aucune importance et n'a pas de signification.