Exercism 的風格指南


本文件是練習中所使用語言與用字的風格指南。

適用範圍

所有練習都應遵循這些規則。 現有的描述與測試案例可以更新以遵循這些規則,不需要「替換」測試案例。

同一個練習內的一致性

有些詞彙有多種正確拼法(例如「lower case」與「lowercase」)。 凡本文件未約定統一寫法的詞彙,在同一份練習內必須保持一致。

例外

如果維護者普遍認為合理,練習可以與這些規則有所不同。 例如,關於不同單位之間換算的練習,可以選擇不使用 SI 單位。

語言

所有內容都應以美式英語撰寫,美式英語與英式英語有許多不同之處。未來可能會有其他翻譯,但 Exercism 的「官方」語言是美式英語。

計量單位

所有計量單位都必須是 SI 或 SI 導出單位。

縮寫、頭字語與字母縮寫

縮寫、頭字語與字母縮寫通常比其他表達方式更難理解,也可能讓想學習的人感到疏遠。

許多縮寫都是行話。情況允許時,請改用其他說法來避免行話。除非符合下列任一情況,否則不要使用縮寫:

  • 縮寫後的詞比未縮寫的詞更為人所知
  • 不使用縮寫會讓文字過於冗長

使用縮寫時,一定要在第一次出現時說明該詞的意思。這通常(但並非總是)包括把縮寫展開。僅僅展開縮寫,往往還不夠。

以下是一些範例規則:

  • 優先使用「if I recall correctly」,而非「IIRC」
  • 優先使用「as far as I know」,而非「AFAIK」
  • 優先使用「queue」,而非「FIFO」;優先使用「stack」,而非「FILO」
  • 不要用「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 (greater than x and less than y)」。
  • 不要使用「esoteric terms」,而應使用「terms not understood by the majority of people」這個說法。

程式碼

所有程式碼都應依照所屬 track 的風格慣例,採用一致的格式。情況允許時,這些 track 通用的慣例應與該語言偏好的風格慣例一致。