Skip to content

Add Style Guide #1713

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

Merged
merged 7 commits into from
Oct 15, 2020
Merged

Add Style Guide #1713

Changes from 1 commit
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
22 changes: 22 additions & 0 deletions STYLE-GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# 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.
In the future other translations may occur, but the "official" Exercism natural langauge is US English.

## Explain or substitude mathmatical and esotoric terms.
Copy link
Contributor

Choose a reason for hiding this comment

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

Could you perhaps add an example of a non-maths esoteric term? The content of this section only mentions maths terms.

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 can't think of one off the top of my head. But I'll try and come up with one and PR it. Feel free to do the same if you can think of one.

Copy link
Member

Choose a reason for hiding this comment

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

I would guess that if I were talking about "lower case" it would be the beer that is lower than the other case of beer. While saying "lowercase" is talking about letters.


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 integers" or "zero and positive integers".
- If we want to use the phrase "rational numbers", it must be explained in the introduction to the exercise.
- Rather than using the word range (which can have different meanings in different contexts) use "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.