Les exercices d'apprentissage sont des exercices conçus pour enseigner des concepts (de programmation) précis.
Les concepts enseignés par les exercices d'apprentissage forment un programme.
Pour en savoir plus sur la conception d'un programme, consulte la documentation sur le programme.
Pour créer rapidement la structure d'un nouvel exercice d'apprentissage, exécute les commandes suivantes depuis le répertoire racine du parcours :
bin/fetch-configlet
bin/configlet create --concept-exercise <slug>
Pour en savoir plus, consulte la documentation de configlet create
Les métadonnées d'un exercice d'apprentissage sont définies dans la clé exercises.concept du fichier config.json. Ces métadonnées définissent l'UUID, le slug et d'autres informations de l'exercice.
Exemple
{
"exercises": {
"concept": [
{
"uuid": "93fbc7cf-3a7e-4450-ad22-e30129c36bb9",
"slug": "cars-assemble",
"name": "Cars, Assemble!",
"concepts": ["if-statements", "numbers"],
"prerequisites": ["basics"]
}
]
}
}
Fichiers
Chaque exercice d'apprentissage possède son propre répertoire dans le répertoire exercises/concept du parcours. Le nom du répertoire de l'exercice d'apprentissage doit correspondre à la propriété slug de l'exercice, telle que définie dans le fichier config.json.
Un exercice d'apprentissage comporte quatre types de fichiers :
Fichiers de documentation
Ces fichiers sont présentés à l'apprenant pour l'aider à comprendre l'exercice.
-
.docs/introduction.md : présente le ou les concepts que l'exercice enseigne à l'apprenant (obligatoire)
-
.docs/instructions.md : fournit les instructions de l'exercice (obligatoire)
-
.docs/hints.md : fournit des indices à l'apprenant pour l'aider à se débloquer dans un exercice (obligatoire)
Ces fichiers ne sont pas présentés à l'apprenant, mais servent à définir les métadonnées de l'exercice.
-
.meta/config.json : contient des méta-informations sur l'exercice (obligatoire)
-
.meta/design.md : décrit la conception de l'exercice (obligatoire)
Fichiers d'approche
Ces fichiers décrivent les approches de l'exercice.
-
.approaches/introduction.md : introduction aux approches les plus courantes de l'exercice (facultatif)
-
.approaches/config.json : métadonnées des approches (facultatif)
-
.approaches/<approach-slug>/content.md : description de l'approche (facultatif)
-
.approaches/<approach-slug>/snippet.txt : extrait illustrant l'approche (facultatif)
Fichiers d'article
Ces fichiers décrivent les articles de l'exercice.
-
.articles/config.json : métadonnées des articles (facultatif)
-
.articles/<article-slug>/content.md : description de l'article (facultatif)
-
.articles/<article-slug>/snippet.md : extrait illustrant l'article (facultatif)
Fichiers d'exercice
Les fichiers propres au langage, comme les fichiers d'implémentation et de tests. Les noms de ces fichiers dépendent du parcours.
- Suite de tests : vérifie l'exactitude d'une solution (obligatoire)
- Implémentation stub : fournit un point de départ aux apprenants (obligatoire)
- Implémentation exemplaire : fournit une implémentation idiomatique qui passe tous les tests (obligatoire)
- Fichiers supplémentaires : garantissent que les tests peuvent s'exécuter (facultatif)
Exemple
exercises
└── concept
└── cars-assemble
├── .approaches
| ├── for-loop
| | ├── content.md
| | └── snippet.txt
| ├── config.json
| └── introduction.md
├── .articles
| ├── performance
| | ├── content.md
| | └── snippet.md
| └── config.json
├── .docs
| ├── introduction.md
| ├── instructions.md
| └── hints.md
├── .meta
| ├── config.json
| ├── design.md
| └── Exemplar.cs (implémentation exemplaire)
├── CarsAssemble.cs (implémentation stub)
└── CarsAssemblyTests.cs (tests)
Spécification minimale valide
Nous privilégions une approche de « fusion optimiste » pour les nouveaux exercices, où les parcours peuvent développer des exercices à l'état de « travail en cours ».
L'état minimal valide, qui passera configlet et permettra de fusionner, est le suivant :
- Une entrée valide dans le
config.json du parcours, avec le status défini sur wip.
- Un fichier
.meta/config.json valide
- La présence des fichiers suivants, même s'ils peuvent être vides :
.docs/introduction.md.docs/instructions.md.docs/hints.md- Implémentation stub
- Fichier de tests
Fichier : .docs/introduction.md
Objectif : présenter le ou les concepts que l'exercice enseigne à l'apprenant.
Présence : obligatoire
- Les informations fournies doivent donner à l'apprenant juste assez de contexte pour qu'il trouve la solution par lui-même.
- Seules les informations nécessaires pour comprendre les fondements du concept et résoudre l'exercice doivent être fournies. Les informations superflues doivent être laissées au document
about.md du concept.
- Les liens doivent être utilisés avec parcimonie, voire pas du tout. Un lien expliquant un sujet complexe comme la récursion peut être utile, mais pour la plupart des concepts, les liens apporteront plus d'informations que nécessaire ; l'objectif doit donc être d'expliquer les choses de façon concise directement dans le texte.
- Il convient d'employer les termes techniques appropriés pour que l'apprenant puisse facilement chercher plus d'informations.
- Les exemples de code ne doivent servir qu'à introduire une nouvelle syntaxe (l'apprenant ne devrait pas avoir besoin de chercher des exemples de syntaxe sur le web). Dans les autres cas, il vaut mieux fournir des descriptions ou des liens plutôt que du code.
À titre d'exemple, l'introduction d'un exercice sur les strings pourrait décrire une string comme une simple « séquence de caractères Unicode » ou une « série d'octets », expliquer comment créer une string et préciser qu'elle possède des méthodes servant à la manipuler. À moins que l'apprenant ait besoin de comprendre des détails plus subtils pour résoudre l'exercice, ce type d'explication brève (avec un exemple de sa syntaxe) devrait suffire à l'apprenant pour résoudre l'exercice.
Exemple
# Introduction
There are two primary ways to assign objects to names in Ruby - using variables or constants. Variables are always written in snake case. A variable can reference different objects over its lifetime. For example, `my_first_variable` can be defined and redefined many times using the `=` operator:
```ruby
my_first_variable = 1
my_first_variable = "Some string"
my_first_variable = SomeComplexObject.new
```
Fichier : .docs/introduction.md.tpl
Objectif : servir de modèle pour générer un fichier introduction.md.
Présence : facultatif
Le document introduction.md présente les concepts de l'exercice à l'apprenant. Chaque concept possède également son propre document introduction.md, qui n'est pas affiché en dehors du contexte d'un exercice.
Si l'introduction du concept doit être reprise telle quelle dans l'introduction de l'exercice, un fichier introduction.md.tpl peut être utilisé. Ce fichier permet de référencer les introductions des concepts au moyen d'espaces réservés : %{concept:<concept-slug>}.
configlet peut générer un fichier introduction.md à partir d'un fichier modèle. Dans le fichier généré, les espaces réservés aux concepts sont remplacés par le contenu introduction du concept.
Le site web d'Exercism ne connaît que le document introduction.md. C'est au parcours qu'il incombe de générer le introduction.md lorsqu'un fichier modèle est utilisé.
Chaque parcours peut décider, exercice par exercice, d'utiliser un modèle ou non. Dans certains cas, reprendre telle quelle l'introduction du concept n'est peut-être pas optimal. Choisis toujours ce qui offre la meilleure expérience d'apprentissage à l'apprenant.
Exemple
# Introduction
%{concept:variables}
Fichier : .docs/instructions.md
Objectif : fournir les instructions de l'exercice.
Présence : obligatoire
Ce fichier se divise en deux parties.
- La première partie raconte l'« histoire » ou le « thème » de l'exercice. Elle ne doit généralement contenir aucun exemple de code.
- La seconde partie donne des instructions claires sur ce que l'apprenant doit faire, sous la forme d'une ou plusieurs tâches.
Chaque tâche doit respecter les règles suivantes :
- Commencer par un titre de niveau 2 débutant par un nombre (par exemple
## 1. Do X, ## 2. Do Y).
- Le titre doit décrire ce qu'il faut implémenter, et non comment l'implémenter (par exemple
## 1. Check if an appointment has already passed).
- Décrire la fonction ou la méthode que l'apprenant doit définir ou implémenter (par exemple
Implement method X(...) that takes an A and returns a Z),
- Fournir un exemple d'utilisation de cette fonction en code. Ces exemples doivent être différents de ceux donnés dans les tests.
Nous tenons beaucoup à ce que le contenu d'Exercism soit sûr pour tout le monde, et nous choisissons donc souvent la prudence lorsqu'il s'agit de décider si une histoire est appropriée ou non. Nous sommes attentifs à ce que nous fusionnons, mais nous savons qu'il est difficile d'avoir conscience de ce qui peut être perçu comme problématique ; nous supposerons donc toujours que tu agis de bonne foi et ferons de notre mieux pour repérer les problèmes lors de la relecture, sans confrontation. Si tu souhaites vérifier une histoire avec nous, mentionne @exercism/leadership et nous l'examinerons ensemble. Voici quelques repères :
- Essaie de t'assurer que l'histoire est accueillante et compréhensible par tout le monde. Si elle contient des blagues internes ou de l'argot régional, cherche des formulations alternatives.
- Essaie d'écrire des exemples inclusifs pour tout le monde. Par exemple, pense à utiliser des noms issus d'autres cultures et des genres variés.
- Demande-toi si tu connais personnellement quelqu'un que cette histoire pourrait offenser. Si c'est le cas, envisage de la modifier pour l'éviter.
Exemple
# Instructions
In this exercise you're going to write some code to help you cook a brilliant lasagna from your favorite cooking book.
## 1. Calculate the remaining oven time in minutes
Define the `Lasagna#remaining_minutes_in_oven` method that takes the actual minutes the lasagna has been in the oven as a parameter and returns how many minutes the lasagna still has to remain in the oven, based on the expected oven time in minutes from the previous task.
```ruby
lasagna = Lasagna.new
lasagna.remaining_minutes_in_oven(30)
# => 10
```
Fichier : .docs/hints.md
Objectif : fournir des indices à l'apprenant pour l'aider à se débloquer dans un exercice.
Présence : obligatoire
- Si l'apprenant est bloqué, nous lui permettons de cliquer sur un bouton pour demander un indice, qui affichera la partie pertinente du fichier.
- Les indices doivent être présentés sous forme de liste à puces sous des titres.
- Les indices doivent suffire à débloquer presque tous les apprenants.
- Les indices ne doivent pas dévoiler la solution, mais plutôt renvoyer vers une ressource qui la décrit (par exemple un lien vers la documentation de la fonction à utiliser).
- Les indices peuvent utiliser des exemples de code pour expliquer des concepts, mais pas pour esquisser la solution. Par exemple, dans un exercice sur les tableaux, ils peuvent montrer un extrait du fonctionnement d'une fonction de tableau, mais pas d'une manière directement copiable-collable dans la solution.
- Les indices généraux sur l'exercice peuvent apparaître sous forme de liste Markdown sous le titre
## General.
- Les indices propres à une tâche doivent apparaître sous forme de liste Markdown sous des titres correspondant au titre de la tâche dans
instructions.md (par exemple ## 2. Do Y).
- S'il n'y a pas d'indices généraux ni d'indices pour une tâche donnée, les titres correspondants doivent être omis. Chaque titre doit être suivi d'une liste Markdown.
- Privilégie les indices propres à une tâche plutôt que les indices généraux, car ils ont plus de chances de débloquer l'apprenant.
- Les titres de tâche doivent décrire ce qu'il faut faire, et non comment le faire.
- Les titres de tâche doivent utiliser la casse de phrase normale (par exemple
## 2. Check if a book can be borrowed).
- Les tâches doivent préciser explicitement la méthode, la fonction ou le type à implémenter, ainsi que la valeur attendue (par exemple
Implement the 'canBorrowBook' function to check if a book can be borrowed. The function takes a book as its parameter and returns `true` if the book has not already been borrowed; otherwise, return `false`).
Consulter les indices n'est pas un chemin « recommandé » et nous décourageons (gentiment) d'y recourir, sauf si l'apprenant ne peut pas avancer sans. Il faut donc garder à l'esprit que l'apprenant qui les lit sera un peu désorienté ou submergé, et peut-être frustré.
Exemple
# Hints
## General
- You need to define a [constant][constant] which should contain the [integer][integers] value specified in the recipe.
## 1. Calculate the remaining oven time in minutes
- You need to define a [method][methods] with a single parameter for the actual time so far.
[constants]: https://www.rubyguides.com/2017/07/ruby-constants/
[integers]: https://ruby-doc.org/core-2.7.0/Integer.html
[methods]: https://launchschool.com/books/ruby/read/methods
Objectif : décrire la conception de l'exercice.
Présence : obligatoire
Ce fichier contient des informations sur la conception de l'exercice : son objectif, ses objectifs pédagogiques, ce qu'il ne faut pas enseigner, etc. Ces informations peuvent être reprises depuis l'issue GitHub correspondante de l'exercice.
Il existe pour informer les futurs mainteneurs ou contributeurs de la portée et des limites d'un exercice, afin d'éviter la tendance naturelle à rendre les exercices plus complexes avec le temps.
Exemple
# Design
## Goal
The goal of this exercise is to teach the student the basics of programming in Ruby.
## Learning objectives
- Know what a variable is.
- Know how to define a variable.
- Know how to update a variable.
## Out of scope
- Memory and performance characteristics.
- Method overloads.
## Concepts
The Concepts this exercise unlocks are:
- `basics`: know what a variable is; know how to define a variable; know how to update a variable.
## Prerequisites
There are no prerequisites.
Objectif : contenir des méta-informations sur l'exercice.
Présence : obligatoire
Ce fichier contient des méta-informations sur l'exercice :
-
authors : le ou les noms d'utilisateur GitHub de l'auteur ou des auteurs de l'exercice (obligatoire)
- Y compris les relecteurs si leurs relectures modifient sensiblement l'exercice (au point qu'on ait l'impression de l'avoir conçu « ensemble »)
-
contributors : le ou les noms d'utilisateur GitHub du ou des contributeurs de l'exercice (facultatif)
- Y compris les relecteurs si leurs relectures sont pertinentes, exploitables ou ont été prises en compte.
-
forked_from : l'exercice ou les exercices dont il est dérivé (obligatoire si l'exercice est dérivé d'un autre)
-
files : les emplacements des fichiers utilisés dans cet exercice, relatifs au répertoire de l'exercice (obligatoire)
-
language_versions : les versions de langage requises (facultatif)
-
blurb : une brève description de cet exercice. Sa longueur doit être <= 350. Markdown n'est pas pris en charge (obligatoire)
-
source : la source sur laquelle cet exercice est basé (facultatif)
-
source_url : l'URL de la source sur laquelle cet exercice est basé (facultatif)
-
representer : les méta-informations liées à la façon dont le representer traite ce fichier (facultatif)
-
version : un entier indiquant la version du representer à utiliser pour l'exercice (obligatoire si la clé parente est présente)
-
icon : le slug de l'icône (voir la liste complète des icônes). S'il n'est pas spécifié, le slug de l'exercice sera utilisé (facultatif)
-
custom : des données non standard propres à l'exercice. Permet de personnaliser le comportement de l'outillage du parcours pour chaque exercice (facultatif)
Si une personne est à la fois auteur et contributeur, ne la liste que comme auteur.
Exemple minimal
{
"authors": ["FSharpForever"],
"files": {
"solution": ["Lasagna.fs"],
"test": ["LasagnaTests.fs"],
"exemplar": [".meta/Exemplar.fs"]
},
"blurb": "Learn the basics of F# by cooking Lucian's Luscious Lasagna"
}
Exemple complet
Supposons que l'utilisateur FSharpForever ait écrit un exercice appelé log-levels pour le parcours F#. PythonProfessor adapte l'exercice pour le parcours Python. Plus tard, l'utilisateur GladToHelp améliore l'exercice.
{
"authors": ["PythonProfessor"],
"contributors": ["GladToHelp"],
"files": {
"solution": ["log_levels.py"],
"test": ["log_levels_test.py"],
"exemplar": [".meta/exemplar.py"],
"editor": ["test_helper.py"]
},
"forked_from": ["fsharp/log-levels"],
"language_versions": ">=3.7",
"blurb": "Learn how to work with strings by processing log lines.",
"source": "Wikipedia",
"source_url": "https://en.wikipedia.org/wiki/Log_file",
"representer": {
"version": 2
},
"icon": "logs",
"custom": {
"parallel": true
}
}
À noter que :
- L'ordre des auteurs et des contributeurs n'est pas significatif et n'a aucune importance.
- Si tu dérives un exercice d'un autre, ne référence pas les auteurs ou contributeurs d'origine. Assure-toi simplement que
forked_from est correct.
- Même si ce n'est pas courant, il est possible de dériver un exercice de plusieurs autres.
-
language_versions est une string de forme libre que les parcours peuvent utiliser et interpréter comme ils le souhaitent.
Fichier : .approaches/introduction.md
Objectif : présenter les approches les plus courantes de l'exercice
Présence : facultatif
Ce fichier décrit les approches les plus courantes de l'exercice.
Consulte la documentation pour savoir ce que ce fichier doit contenir.
Exemple
# Introduction
The key to this exercise is to deal with C# strings being immutable, which means that a `string`'s value cannot be changed.
Therefore, to reverse a string you'll need to create a _new_ `string`.
## Using LINQ
```csharp
public static string Reverse(string input)
{
return new string(input.Reverse().ToArray());
}
```
For more information, check the [LINQ approach][approach-linq].
## Which approach to use?
If readability is your primary concern (and it usually should be), the LINQ-based approach is hard to beat.
Fichier : .approaches/config.json
Objectif : les métadonnées des approches
Présence : facultatif (obligatoire lorsqu'une introduction d'approche ou une approche existe)
Ce fichier contient des méta-informations sur les approches de l'exercice :
Exemple
{
"introduction": {
"authors": ["erikschierboom"]
},
"approaches": [
{
"uuid": "448fb2b4-18ab-4e55-aa54-ad4ed6d5f7f6",
"slug": "span",
"title": "Use Span<T>",
"blurb": "Use Span<T> to efficiently reverse a string.",
"authors": ["erikschierboom"]
}
]
}
Fichier : .approaches/<approach-slug>/content.md
Objectif : une description détaillée de l'approche
Présence : facultatif (obligatoire pour les approches)
Ce fichier contient une description détaillée de l'approche.
Consulte la documentation pour savoir ce que ce fichier doit contenir.
Exemple
# Span
```csharp
Span<char> chars = stackalloc char[input.Length];
for (var i = 0; i < input.Length; i++)
{
chars[input.Length - 1 - i] = input[i];
}
return new string(chars);
```
This `Span<T>` approach uses a `for` loop.
Fichier : .approaches/<approach-slug>/snippet.txt
Objectif : un extrait illustrant l'approche
Présence : facultatif (obligatoire pour les approches)
Ce fichier contient un petit extrait qui illustre l'approche.
Cet extrait est affiché sur la page « Creuse plus loin » de l'exercice.
Son nombre de lignes doit être <= 8.
Consulte la documentation pour savoir ce que ce fichier doit contenir.
Exemple
Span<char> chars = stackalloc char[input.Length];
for (var i = 0; i < input.Length; i++)
{
chars[input.Length - 1 - i] = input[i];
}
return new string(chars);
Fichier : .article/config.json
Objectif : les métadonnées des articles
Présence : facultatif (obligatoire lorsqu'un article existe)
Ce fichier contient des méta-informations sur les articles de l'exercice :
-
articles : un tableau listant les articles détaillés (facultatif)
-
uuid : un UUID V4 qui identifie l'article de façon unique. L'UUID doit être unique au sein du parcours comme sur l'ensemble des parcours, et ne doit jamais changer
-
slug : le slug de l'article, une string en minuscules au format kebab-case. Le slug doit être unique parmi tous les slugs d'article du parcours. Sa longueur doit être <= 255.
-
title : le titre de l'article. Sa longueur doit être <= 255.
-
blurb : une brève description de cet article. Sa longueur doit être <= 350. Markdown n'est pas pris en charge (obligatoire)
-
authors : le ou les noms d'utilisateur GitHub du ou des auteurs de l'article (obligatoire)
- Y compris les relecteurs si leurs relectures modifient sensiblement l'article (au point qu'on ait l'impression de l'avoir conçu ensemble)
-
contributors : le ou les noms d'utilisateur GitHub du ou des contributeurs de l'article (facultatif)
- Y compris les relecteurs si leurs relectures sont pertinentes, exploitables ou ont été prises en compte.
Exemple
{
"articles": [
{
"uuid": "6db71962-62d5-448b-a980-c20ae41013ed",
"slug": "performance",
"title": "Optimizing performance",
"blurb": "Explore how to most efficiently reverse a string and what the trade-offs are.",
"authors": ["erikschierboom"]
}
]
}
Fichier : .articles/<article-slug>/content.md
Objectif : une description détaillée de l'approche
Présence : facultatif (obligatoire pour les approches)
Ce fichier contient une description détaillée de l'approche.
Consulte la documentation pour savoir ce que ce fichier doit contenir.
Exemple
# Performance
In this document, we'll find out which approach is the most performant one.
## Benchmark results
| Method | Mean | Error | StdDev | Median | Allocated |
| -----: | --------: | --------: | --------: | --------: | --------: |
| Linq | 29.133 ns | 0.5865 ns | 0.5486 ns | 28.984 ns | 80 B |
| Array | 4.806 ns | 0.4999 ns | 1.4739 ns | 3.967 ns | - |
Fichier : .articles/<article-slug>/snippet.txt
Objectif : un extrait illustrant l'approche
Présence : facultatif (obligatoire pour les articles)
Ce fichier contient un petit extrait qui illustre l'article.
Cet extrait est affiché sur la page « Creuse plus loin » de l'exercice.
Son nombre de lignes doit être <= 8.
Consulte la documentation pour savoir ce que ce fichier doit contenir.
Exemple
| Method | Mean | Allocated |
| -----: | --------: | --------: |
| Linq | 29.133 ns | 80 B |
| Array | 4.806 ns | - |
Fichier : implémentation stub
Objectif : fournir un point de départ aux apprenants.
Présence : obligatoire
- Conçois le stub de manière que l'apprenant sache où ajouter du code.
- Définis des stubs pour toute syntaxe qui n'est pas introduite dans l'exercice. Pour la plupart des exercices, cela signifie définir des fonctions ou des méthodes stub.
- Pour les langages compilés, essaie de fournir du code compilable, car les messages du compilateur sont parfois difficiles à comprendre pour les apprenants qui débutent dans le langage.
- Le code doit être aussi simple que possible.
- N'utilise que les fonctionnalités du langage introduites par l'exercice ou ses prérequis (et leurs prérequis, et ainsi de suite).
- Le fichier stub est montré à l'apprenant lorsqu'il utilise l'éditeur en ligne et est téléchargé sur son système de fichiers lorsqu'il utilise la CLI.
- Les chemins relatifs vers le ou les fichiers d'implémentation stub doivent être spécifiés dans la clé
"files.solution" du fichier .meta/config.json.
Exemple
class Lasagna
def remaining_minutes_in_oven(actual_minutes_in_oven)
raise NotImplementedError, 'Please implement the Lasagna#remaining_minutes_in_oven method'
end
def preparation_time_in_minutes(layers)
raise NotImplementedError, 'Please implement the Lasagna#preparation_time_in_minutes method'
end
end
Fichier : tests
Objectif : vérifier l'exactitude d'une solution.
Présence : obligatoire
- Les tests ne doivent pas reprendre les exemples du fichier
instructions.md.
- Le code doit être aussi simple que possible.
- N'utilise que les fonctionnalités du langage introduites par les prérequis de l'exercice (et leurs prérequis, et ainsi de suite).
- Le fichier de tests n'est pas montré à l'apprenant lorsqu'il utilise l'éditeur en ligne, mais est téléchargé sur son système de fichiers lorsqu'il utilise la CLI.
- Les chemins relatifs vers le ou les fichiers de tests doivent être spécifiés dans la clé
"files.test" du fichier .meta/config.json.
Exemple
require 'minitest/autorun'
require_relative 'lasagna'
class LasagnaTest < Minitest::Test
def test_remaining_minutes_in_oven
assert_equal 15, Lasagna.new.remaining_minutes_in_oven(25)
end
def test_preparation_time_in_minutes_with_one_layer
assert_equal 2, Lasagna.new.preparation_time_in_minutes(1)
end
def test_preparation_time_in_minutes_with_multiple_layers
assert_equal 8, Lasagna.new.preparation_time_in_minutes(4)
end
end
Fichier : implémentation exemplaire
Objectif : fournir l'implémentation cible que l'apprenant doit viser.
Présence : obligatoire
- Cette implémentation est le code cible que nous voulons que l'apprenant atteigne.
- Les mentors verront ce code comme la « cible » lorsqu'ils rédigent leurs retours
- L'implémentation ne doit utiliser que les fonctionnalités du langage introduites par l'exercice ou ses prérequis (et leurs prérequis, et ainsi de suite).
- Le fichier exemplaire n'est pas montré à l'apprenant lorsqu'il utilise l'éditeur en ligne et n'est pas téléchargé sur son système de fichiers lorsqu'il utilise la CLI.
- Le fichier exemplaire sera montré aux mentors lorsqu'ils commentent des solutions ou des représentations.
- Les chemins relatifs vers le ou les fichiers d'implémentation exemplaire doivent être spécifiés dans la clé
"files.exemplar" du fichier .meta/config.json.
Exemple
class Lasagna
EXPECTED_MINUTES_IN_OVEN = 40
PREPARATION_MINUTES_PER_LAYER = 2
def remaining_minutes_in_oven(actual_minutes_in_oven)
EXPECTED_MINUTES_IN_OVEN - actual_minutes_in_oven
end
def preparation_time_in_minutes(layers)
layers * PREPARATION_MINUTES_PER_LAYER
end
end
Fichier : fichiers supplémentaires
Objectif : garantir que les tests peuvent s'exécuter.
Présence : obligatoire si les fichiers par défaut ne suffisent pas à exécuter les tests
Certains langages nécessitent des fichiers supplémentaires pour que les tests s'exécutent. C'est par exemple le cas des fichiers de projet C# et des fichiers package.json de Node, sans lesquels il est impossible d'exécuter les tests.
Fichiers partagés
Certains fichiers ne sont pas propres à un exercice en particulier, mais s'appliquent à tous les exercices. Consulte la documentation pour en savoir plus.
Nommage
Les exercices d'apprentissage doivent être nommés d'après leur histoire ou leur thème, et non d'après leur ou leurs concepts.
Bons exemples de noms :
Tim from MarketingLucian's Luscious LasagnaCalculator Conundrum
Noms interdits :
-
Booleans : utilise un nom de concept, pas un nom d'histoire
-
Exercise #1 : un exercice n'est pas une histoire ou un thème
Lorsque tu dérives un exercice sans changements majeurs, utilise le nom d'origine quand c'est possible.
Slugs
Chaque exercice possède également un slug, qui est la version normalisée du nom de l'exercice selon les règles suivantes :
- Utiliser les minuscules.
- Utiliser le format
kebab-case.
- Utiliser des caractères alphanumériques latins et des tirets (expression régulière :
[a-z0-9-]+)
- Préférer les nombres écrits en toutes lettres aux chiffres, sauf s'il y a une raison particulière de préférer le chiffre (par exemple
two-fer plutôt que 2-fer)
Bons exemples de slugs :
tim-from-marketinglucians-luscious-lasagnacalculator-conundrum
Slugs interdits :
-
TIM-FROM-MARKETING : n'utilise pas les minuscules (c'est-à-dire tim-from-marketing)
-
TimFromMarketing : n'utilise pas le format kebab-case (c'est-à-dire tim-from-marketing)
-
floating-point-numbers : utilise un nom de concept, pas un nom d'histoire
Présentation
La façon dont la documentation d'un exercice est présentée à l'apprenant diffère selon qu'il utilise l'éditeur en ligne ou la CLI. Consulte ce document pour en savoir plus.
Icône
Chaque exercice possède une icône associée.
Par défaut, l'icône affichée est celle dont le nom correspond au slug de l'exercice.
Tu peux la remplacer en spécifiant la propriété icon dans le fichier .meta/config.json de l'exercice.
Si tu dérives un exercice existant, il existe probablement déjà une icône pour cet exercice.
Sinon, ouvre une issue dans le dépôt website-icons.
