概念

概念是程式設計師要精通一門語言時必須理解的東西。概念會透過概念練習來傳授，並做為概念練習與練習題的先修項目。在向學生顯示時，概念會被放到概念圖上。

中繼資料

概念的中繼資料定義在 config.json 檔案裡的 concepts 鍵中。這些中繼資料定義了概念的 UUID、slug 等資訊。

範例

{
  "concepts": [
    {
      "uuid": "b9a421b2-c5ff-4213-bd6d-b886da31ea0d",
      "slug": "numbers",
      "name": "Numbers"
    }
  ]
}

檔案

每個概念在軌道的 concepts 目錄下都有自己專屬的目錄。概念目錄的名稱必須與該概念的 slug 屬性一致，也就是 config.json 檔案裡定義的值。

一個概念有兩種類型的檔案：

說明文件

這些檔案會呈現給學生，用來協助說明概念。

• about.md：為已完成對應概念練習的學生提供概念的相關資訊，方便他們學習與日後查閱（必要）
• introduction.md：為尚未完成對應概念練習的學生提供簡短介紹（必要）
• links.json：提供實用的連結，讓學生能進一步閱讀或取得概念的相關資訊（必要）

中繼資料檔案

這些檔案不會呈現給學生，而是用來定義概念的中繼資料。

• .meta/config.json：包含概念的中繼資料（必要）

範例

concepts
└── numbers
    ├── .meta
    |   └── config.json
    ├── about.md
    ├── introduction.md
    └── links.json

檔案：about.md

**用途：**為已完成對應概念練習的學生，提供更詳細的概念資訊，方便他們學習與日後查閱。

**是否必要：**是

完成對應的概念練習（也就是「學會」一個概念）之後，概念頁面會顯示 about.md的內容，而不是 introduction.md。about.md應該為學生提供完整的資訊，說明他們要精通這個概念需要知道什麼。至少，這個檔案應該包含概念的 introduction.md 文件中介紹過的所有資訊。

如果概念會介紹新的語法，就應該附上語法範例。學生不應該需要點開一大堆連結，才能獲得這個檔案想傳達的知識。about.md應該包含足夠的資訊，讓內容在其脈絡下就能理解。

about.md的內容並不受限於對應概念練習的範圍。內容可以需要其他之後才會介紹的概念知識。如果文中提到其他概念，就應該連結到它們各自的簡介（詳見內部連結）。

以下是幾個可能涵蓋的主題範例。

• 概念的常見用法
• 使用概念時常見的陷阱（例如沒有考慮到執行緒安全）
• 可能讓毫無防備的開發者吃虧的使用限制
• 其他概念所探討的替代做法（例如遞迴概念可能會提到，高階函式概念為類似的問題提供了另一種解法）
• 為了方便學習或配合 Exercism 環境所做的取捨，例如在同一個檔案裡放多個類別
• 可能與該概念混淆的相似功能
• 效能特性與記憶體用量，前提是這在該語言中是常見的考量
• 不要在文中提及特定的練習，因為這個檔案會顯示在練習的脈絡之外。

about.md的目的不是提供概念完整無缺的資訊。舉例來說，假設某個語言有一些較舊的功能，有經驗的程式設計師（甚至官方文件或規格）建議不要再使用它們。在 about.md裡詳細介紹這類功能就超出了範圍，因為它們與培養精通度無關。不過，如果學生平常就可能遇到這些舊標準，維護者可以選擇加上一小段來提醒這些舊標準。不過，這一小段應該標明其性質。

about.md的結構必須清楚，尤其是在包含大量資訊的時候。未來也會支援將部分內容標示為「進階主題」，讓有興趣的學生能注意到，同時不會讓其他人負擔過重。

範例

# About

There are two different kinds of numbers in Elixir - integers and floats.

Floats are numbers with one or more digits behind the decimal separator. They use the 64-bit double precision floating-point format.

```elixir
float = 3.45
# => 3.45
```

Elixir also supports the scientific notation for floats.

```elixir
1.25e-2
# => 0.0125
```

## Rounding errors

Floats are infamous for their rounding errors.

```elixir
0.1 + 0.2
# => 0.30000000000000004
```

However, those kind of errors are not specific to Elixir. They happen in all programming languages. This is because all data on our computers is stored and processed as binary code. In binary, only fractions whose denominator can be expressed as `2^n` (e.g. `1/4`, `3/8`, `5/16`) can be expressed exactly. Other fractions are expressed as estimations.

```elixir
# 3/4
Float.ratio(0.75)
# => {3, 4}

# 3/5
Float.ratio(0.6)
# => {5404319552844595, 9007199254740992}
```

You can learn more about this problem at [0.30000000000000004.com][0.30000000000000004.com]. The [Float Toy page][evanw.github.io-float-toy] has a nice, graphical explanation how a floating-point number's bits are converted to an actual floating-point value.

檔案：introduction.md

**用途：**為尚未完成對應概念練習的學生提供簡短介紹。

**是否必要：**是

如果學生尚未完成對應的概念練習，就會顯示這個檔案。它應該提供概念的簡短介紹。

• 只提供理解概念基礎所需的資訊。額外的資訊留給 about.md。
• 連結應該盡量少用，甚至不用。雖然解釋像遞迴這類複雜主題的連結可能很有用，但對大多數概念來說，連結提供的資訊會超出所需，因此目標應該是直接在文中簡潔地說明。
• 應該使用正確的技術術語，讓學生能輕鬆搜尋到更多資訊。
• 只有在介紹新語法時才使用程式碼範例（學生不應該需要上網搜尋語法範例）。其他情況請改用描述或連結，而不是程式碼。
• 不要在文中提及特定的練習，因為這個檔案會顯示在練習的脈絡之外。

範例

# Introduction

One of the key aspects of working with numbers in C# is the distinction between integers and floating-point numbers (numbers with zero or more digits after the decimal separator).

The two most commonly used numeric types in C# are `int` (a 32-bit integer) and `double` (a 64-bit floating-point number).

```csharp
int i = 123;
double d = 54.29;
```

檔案：links.json

**用途：**提供實用的連結，讓學生能進一步閱讀或取得概念的相關資訊。

**是否必要：**是

這些可能是官方文件、很棒的教學等等。這些連結不會取代概念的 about.md裡更貼近脈絡的連結，而是為學生提供一組快速、宏觀的參考資源。

每個連結都必須包含下列欄位：

• url：連結指向的 URL。
• description：連結的說明，會顯示為連結文字。

連結也可以選擇性地加上 icon_url 欄位，用來自訂連結顯示時所顯示的圖示。如果沒有指定，圖示會預設為 favicon。

[
  {
    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/intro-to-csharp/numbers-in-csharp-local",
    "description": "Numbers in C#"
  },
  {
    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/integral-numeric-types",
    "description": "Integral numeric types",
    "icon_url": "http://test.org/icon.png"
  }
]

---

檔案：.meta/config.json

**用途：**包含概念的中繼資料。

**是否必要：**是

這個檔案包含概念的中繼資料：

• authors：概念作者的 GitHub 使用者名稱（必要）
  • 如果審閱者的意見大幅改變了概念（大到讓人覺得「你們是一起完成的」），也可以列入
• contributors：概念貢獻者的 GitHub 使用者名稱（選填）
  • 如果審閱者的意見有意義、可付諸實行或已被採用，也可以列入。
• blurb：這個概念的簡短說明。長度必須 <= 350。不支援 Markdown（必要）

如果某人同時是作者也是貢獻者，只將他列為作者。

範例

{
  "authors": ["FSharpForever"],
  "contributors": ["IWantToHelp"],
  "blurb": "F# has two types of numbers: integers and floating-point numbers."
}

請注意：

• 作者與貢獻者的順序不重要，也不具任何意義。