Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Style Guide #1713

Merged
merged 7 commits into from
Oct 15, 2020
Merged

Add Style Guide #1713

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6bf2174
Add Style Guide
iHiD Oct 15, 2020
fd860b3
Update STYLE-GUIDE.md
iHiD Oct 15, 2020
5e95607
Update STYLE-GUIDE.md
iHiD Oct 15, 2020
9d6034e
Update STYLE-GUIDE.md
cmcaine Oct 15, 2020
2bb8c22
Update STYLE-GUIDE.md
iHiD Oct 15, 2020
ce63702
Update STYLE-GUIDE.md
iHiD Oct 15, 2020
b90aab0
Update STYLE-GUIDE.md
iHiD Oct 15, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions STYLE-GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Exercism's Style Guide

This document acts as a Style Guide for the language and wording used in exercises.

## General principle

All content should be written in US English.
All units of measurement must be [SI](https://en.wikipedia.org/wiki/International_System_of_Units) or [SI-derived](https://en.wikipedia.org/wiki/SI_derived_unit) units.
In the future other translations may occur, but the "official" Exercism language is US English.

## Explain or substitute mathematical and esoteric terms.
iHiD marked this conversation as resolved.
Show resolved Hide resolved

In any place that mathematical terms are used they should be explained or substituted out for terms that require less domain knowledge.

Examples:
- Rather than using "natural numbers", we should use "positive whole numbers".
- If we want to use the phrase "rational numbers", it must be explained in the introduction to the exercise.
iHiD marked this conversation as resolved.
Show resolved Hide resolved
- Rather than using the word range (which can have different meanings in different contexts) use "x < ? < y (greater than x and less than y)".

## Use consistency within an exercise.

There are some terms that have multiple valid spellings (e.g. "lower case" vs "lowercase").
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps this could be the first example of an agreed spelling?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure. But I also want a rule that explains what happens when multiple valid spellings are used without a documented decision in this guide (ie, they should be exercise-consistent)

Copy link
Member

@rpottsoh rpottsoh Oct 15, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lowercase seems to be more popular:
image

https://english.stackexchange.com/questions/59409/lowercase-lower-case-or-lower-case
oO

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good enough for me 👍

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

More popular != correct 😜

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd agree with lowercase, but I think this falls into the "it doesn't matter as long as its consistent within an exercise" bucket. Unless anyone feels strongly about this particular word, and wants to encode lowercase as a rule and find me another example for this bit :)

Where a consistent style has not been agreed within this document, these must be consistent within an exercise.