This document acts as a Style Guide for the language and wording used in exercises.
These rules should be followed in all exercises. Existing descriptions and test-cases can be updated to adhere to them without requiring "replacement" test cases.
There are some terms that have multiple valid spellings (e.g. "lower case" vs "lowercase"). Where a consistent style has not been agreed within this document, these must be consistent within an exercise.
Exercises may vary from these rules if there is general consensus across maintainers that this is reasonable. For example, an exercise about converting between different units might choose not to use SI measurements.
All content should be written in US English, which differs from UK English in a variety of ways. In the future other translations may occur, but the "official" Exercism language is US English.
Abbreviations, acronyms and initialisms are often more difficult to understand than other phrasing options, and can alienate people trying to learn.
Many abbreviations are jargon. Avoid jargon where possible by using alternative language. Don't use abbreviations unless either:
When using abbreviations always explain what the term means on its first use. This will often, but not always, include expanding the abbreviation. It will rarely be sufficient to only expand the abbreviation.
Here are some example rules:
And some examples of good usage:
Use the "Oxford Comma" (also known as the Serial Comma) in lists. For example, rather than "I love my parents, Lady Gaga and Humpty Dumpty", write "I love my parents, Lady Gaga, and Humpty Dumpty". You may also enjoy this image as an explanation.
Some abbreviations are considered common, useful, and non-technical enough that we have decided to permit them:
Contractions (e.g. "won't", "I'm", "that's") should be used sparingly if at all in exercise descriptions, but are not restricted in other language around the site (e.g. website copy, mentoring).
Many American English style guides state that the abbreviations "i.e." and "e.g." should be followed by a comma (see, e.g., this StackExchange thread). This is permitted, but not required within text on Exercism.
In any place that mathematical terms are used they should be explained or substituted out for terms that require less domain knowledge.
All code should be consistently formatted using the style conventions of their track. When possible, these track-wide conventions should match the language's preferred style conventions.