Ce document sert de guide de style pour la langue et la formulation utilisées dans les exercices.
Champ d'application
Ces règles doivent être suivies dans tous les exercices.
Les descriptions et les cas de test existants peuvent être mis à jour pour s'y conformer, sans qu'il faille créer des cas de test « de remplacement ».
Cohérence au sein d'un exercice
Certains termes admettent plusieurs orthographes valides (par exemple « lower case » ou « lowercase »). Quand ce document n'a pas arrêté de style uniforme, l'orthographe doit rester cohérente au sein d'un même exercice.
Exceptions
Un exercice peut s'écarter de ces règles si les mainteneurs s'accordent largement sur le fait que c'est raisonnable. Par exemple, un exercice portant sur la conversion entre différentes unités peut choisir de ne pas utiliser les unités SI.
Langue
Tout le contenu doit être écrit en anglais américain, qui diffère de l'anglais britannique de diverses manières. D'autres traductions verront peut-être le jour à l'avenir, mais la langue « officielle » d'Exercism est l'anglais américain.
Unités de mesure
Toutes les unités de mesure doivent être des unités SI ou dérivées du SI.
Abréviations, acronymes et sigles
Les abréviations, les acronymes et les sigles sont souvent plus difficiles à comprendre que d'autres formulations et peuvent rebuter les personnes qui essaient d'apprendre.
Beaucoup d'abréviations relèvent du jargon. Évite le jargon quand c'est possible en choisissant une autre formulation. N'utilise une abréviation que dans l'un des cas suivants :
- la forme abrégée est mieux connue que la forme développée
- le texte deviendrait excessivement long sans abréviation
Quand tu utilises une abréviation, explique toujours ce que le terme signifie à sa première utilisation. Cela implique souvent, mais pas toujours, de développer l'abréviation. Il est rarement suffisant de se contenter de la développer.
Voici quelques exemples de règles :
- Préfère « if I recall correctly » à « IIRC »
- Préfère « as far as I know » à « AFAIK »
- Préfère « queue » à « FIFO » et « stack » à « FILO »
- Au lieu de décrire une interface comme « RESTful », décris ses propriétés précises
- Si tu dois utiliser « CRUD », explique qu'il signifie Create, Read, Update, Delete et qu'il s'agit des actions de base des bases de données standard
Et quelques exemples de bon usage :
- « HyperText Markup Language (HTML) is the language used to describe document structure and content on the web » (développé et expliqué)
- « DNA, a set of chemical instructions that influence how our bodies are constructed » (DNA n'est pas développé, car « deoxyribonucleic acid » ne serait probablement pas utile pour expliquer ce qu'est l'ADN à notre public)
- « NASA, the United States' space agency, launched the Mariner 2 space probe in... » (NASA n'est pas développé, car « National Aerospace and Space Administration » est bien mieux connu sous son sigle que sous sa forme développée)
- « The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV » (définis DMV à sa première utilisation)
Grammaire
Virgule d'Oxford
Utilise la virgule d'Oxford (aussi appelée virgule de série) dans les listes. Par exemple, au lieu d'écrire « I love my parents, Lady Gaga and Humpty Dumpty », écris « I love my parents, Lady Gaga, and Humpty Dumpty ». Tu apprécieras peut-être aussi cette image qui l'explique.
Exceptions
Certaines abréviations sont jugées assez courantes, utiles et non techniques pour qu'on ait décidé de les autoriser :
-
e.g. ou eg
-
i.e. ou ie
-
etc. ou etc
docs
Les contractions (par exemple « won't », « I'm », « that's ») doivent être employées avec parcimonie, voire pas du tout, dans les descriptions d'exercices, mais elles ne sont pas interdites dans les autres contenus du site (par exemple les textes du site web, le mentorat).
De nombreux guides de style de l'anglais américain indiquent que les abréviations « i.e. » et « e.g. » doivent être suivies d'une virgule (voir, par exemple, ce fil StackExchange). C'est autorisé, mais pas obligatoire dans les textes sur Exercism.
Choix des mots
Termes mathématiques et jargon
Partout où des termes mathématiques sont employés, ils doivent être expliqués ou remplacés par des termes qui demandent moins de connaissances du domaine.
Exemples :
- Plutôt que d'utiliser « natural numbers », on devrait dire « positive whole numbers ».
- Si l'on veut employer l'expression « rational numbers », elle doit être expliquée dans l'introduction de l'exercice.
- Plutôt que d'utiliser le mot « range » (qui peut avoir des sens différents selon le contexte), utilise « x < ? < y (greater than x and less than y) ».
- Plutôt que d'utiliser « esoteric terms », utilise l'expression « terms not understood by the majority of people ».
Code
Tout le code doit être formaté de manière cohérente, selon les conventions de style de son parcours. Quand c'est possible, ces conventions, valables pour tout le parcours, doivent correspondre aux conventions de style préférées du langage.
