この文書は、演習で使われる言葉遣いと表現のスタイルガイドです。
適用範囲
これらのルールは、すべての演習で守ってください。
既存の説明文やテストケースは、「置き換え用」のテストケースを用意することなく、これらのルールに合わせて更新できます。
1つの演習内での一貫性
複数の正しい綴りがある用語もあります（例：「lower case」と「lowercase」）。
この文書内で一貫したスタイルが合意されていないものについては、1つの演習の中では一貫させてください。
例外
メンテナー全体で、それが妥当だという共通認識があれば、演習がこれらのルールから外れてもかまいません。
たとえば、異なる単位の変換を扱う演習では、SI単位を使わないという選択もありえます。
言語
すべてのコンテンツはアメリカ英語で書いてください。アメリカ英語は、さまざまな点でイギリス英語と異なります。将来、ほかの言語への翻訳が行われる可能性はありますが、Exercismの「公式」言語はアメリカ英語です。
単位
すべての計量単位は、SIまたはSI組立単位でなければなりません。
略語・頭字語・イニシャリズム
略語や頭字語、イニシャリズムは、ほかの言い回しよりも理解しづらいことが多く、学ぼうとしている人を遠ざけてしまうことがあります。
略語の多くは専門用語です。できるだけ別の言葉を使い、専門用語は避けてください。次のいずれかに当てはまる場合を除いて、略語は使わないでください。
- 略した形のほうが、略さない形よりもよく知られている
- 略さないと、文章がひどく冗長になる
略語を使うときは、必ず最初に使う時点で、その用語が何を意味するのかを説明してください。説明には略語を展開することが含まれる場合が多いですが、いつもそうとは限りません。また、略語を展開するだけでは足りないことがほとんどです。
ルールの例をいくつか挙げます。
- 「IIRC」ではなく「if I recall correctly」を使ってください
- 「AFAIK」ではなく「as far as I know」を使ってください
- 「FIFO」ではなく「queue」、「FILO」ではなく「stack」を使ってください
- インターフェースを「RESTful」と説明するのではなく、その具体的な性質を説明してください
- どうしても「CRUD」を使う必要があるなら、Create、Read、Update、Deleteの頭文字であり、標準的なデータベースにおける基本操作を表すことを説明してください
よい使用例もいくつか挙げます。
- "HyperText Markup Language (HTML) is the language used to describe document structure and content on the web" （展開して説明している）
- "DNA, a set of chemical instructions that influence how our bodies are constructed" （DNAを展開していないのは、「deoxyribonucleic acid」が読者にとってDNAの説明に役立つ可能性が低いため）
- "NASA, the United States' space agency, launched the Mariner 2 space probe in..." （NASAを展開していないのは、「National Aerospace and Space Administration」よりも略語のほうがはるかによく知られているため）
- "The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV" （DMVは最初に使う時点で定義している）
文法
オックスフォード・カンマ
リストでは「オックスフォード・カンマ」（シリアル・カンマとも呼ばれます）を使ってください。たとえば、「I love my parents, Lady Gaga and Humpty Dumpty」ではなく「I love my parents, Lady Gaga, and Humpty Dumpty」と書きます。この画像も説明として楽しめるかもしれません。
例外
なかには、よく使われ、便利で、十分に非技術的だと判断され、使用を認めている略語もあります。
-
e.g.またはeg
-
i.e.またはie
-
etc.またはetc
docs
短縮形（例：「won't」「I'm」「that's」）は、演習の説明ではできるだけ使わず、使う場合も控えめにしてください。ただし、サイト内のほかの文章（ウェブサイトの文言やメンタリングなど）では制限していません。
アメリカ英語のスタイルガイドの多くは、「i.e.」と「e.g.」のあとにカンマを置くべきだと述べています（例として、このStackExchangeのスレッドを参照してください）。Exercism上の文章では、これは許可されていますが、必須ではありません。
言葉の選び方
数学用語と専門用語
数学用語を使う場合は、必ず説明するか、専門知識をあまり必要としない言葉に置き換えてください。
例：
- 「natural numbers」ではなく「positive whole numbers」を使います。
- 「rational numbers」という表現を使うなら、演習の導入で説明しなければなりません。
- rangeという単語（文脈によって意味が変わりえます）ではなく、「x < ? < y（xより大きく、yより小さい）」を使ってください。
- 「esoteric terms」ではなく「terms not understood by the majority of people」という表現を使ってください。
コード
すべてのコードは、そのトラックのスタイル規約に沿って一貫した書式で書いてください。可能であれば、トラック全体の規約は、そのプログラミング言語が推奨するスタイル規約に合わせるのがよいでしょう。
