概念

コンセプトとは、あるプログラミング言語を使いこなすためにプログラマーが理解しておくべき事柄です。 コンセプトはコンセプト演習で教えられ、コンセプト演習とプラクティス演習の前提条件として使われます。 コンセプトは、学習者に表示されるときにコンセプトマップ上に配置されます。

メタデータ

コンセプトのメタデータは、config.jsonファイルのconceptsキーで定義します。このメタデータには、コンセプトのUUIDやスラッグなどが定義されます。

例

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

ファイル

各コンセプトは、トラックのconceptsディレクトリの中にそれぞれ専用のディレクトリを持ちます。コンセプトのディレクトリ名は、config.jsonファイルで定義されているコンセプトのslugプロパティと一致していなければなりません。

コンセプトには2種類のファイルがあります。

ドキュメントファイル

これらのファイルは、コンセプトの理解を助けるために学習者に提示されます。

  • about.md: 対応するコンセプト演習を完了した学習者が、そこから学び直したり参照したりできるように、コンセプトに関する情報を提供します（必須）
  • introduction.md: 対応するコンセプト演習をまだ完了していない学習者に、コンセプトの簡単な導入を提供します（必須）
  • links.json: コンセプトについてさらに読んだり調べたりするための役立つリンクを提供します（必須）

メタデータファイル

これらのファイルは学習者には_提示されず_、コンセプトのメタデータを定義するために使われます。

  • .meta/config.json: コンセプトに関するメタ情報が含まれます（必須）

例

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

ファイル: about.md

目的: 対応するコンセプト演習を完了した学習者が、そこから学び直したり参照したりできるように、コンセプトについてより詳しい情報を提供すること。

要否: 必須

対応するコンセプト演習を完了すると（これをコンセプトを「学習した」状態と呼びます）、コンセプトページにはintroduction.mdファイルの代わりにabout.mdファイルの内容が表示されます。about.mdファイルでは、そのコンセプトを使いこなすために知っておくべきことを、学習者に網羅的に提供する必要があります。最低限、このファイルには、コンセプトのintroduction.mdドキュメントで紹介されるすべての情報が含まれている必要があります。

コンセプトで新しい構文を紹介する場合は、構文の例を含める必要があります。学習者が、このファイルで伝えようとしている知識を得るために、多くのリンクをたどらなければならないようではいけません。むしろ、about.mdは、その文脈の中で理解できるだけの情報を含んでいるべきです。

about.mdファイルは、対応するコンセプト演習の範囲に限定されません。内容が、あとで紹介されるほかのコンセプトの知識を必要とすることもあります。ほかのコンセプトに言及する場合は、それぞれの導入ドキュメントにリンクを張ってください（詳しくは内部リンクを参照）。

ここでは、扱える内容の例をいくつか挙げます。

  • そのコンセプトでよく使われる用法
  • コンセプトを使ううえでよくある落とし穴（例: スレッドセーフを考慮し忘れる）
  • 何も知らないエンジニアがつまずきかねない使用上の制限
  • ほかのコンセプトで扱われる別のアプローチ（例: 再帰のコンセプトが、高階関数のコンセプトで同様の問題に対する別のアプローチを提供していることに触れることがあります）
  • 学習しやすさやExercismの環境に合わせるための妥協（例: 複数のクラスを1つのファイルにまとめる）
  • そのコンセプトと混同しやすい似た機能
  • その言語で一般的に考慮される、パフォーマンス特性やメモリ使用量
  • このファイルは演習の文脈の外で表示されるため、本文中で特定の演習に言及しないでください。

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;
```

目的: コンセプトについてさらに読んだり調べたりするための役立つリンクを提供すること。

要否: 必須

公式ドキュメントや優れたチュートリアルなどが考えられます。これらのリンクは、コンセプトのabout.mdファイル内にある、より文脈に沿ったリンクの代わりになるものでは_ありません_が、学習者にとって手早く参照できる大まかな手がかりを提供します。

各リンクには、次のフィールドを含める必要があります。

  • url: リンク先のURL。
  • description: リンクの説明。リンクテキストとして表示されます。

リンクには任意でicon_urlフィールドを付けることもできます。これは、リンクを表示するときに使うアイコンをカスタマイズするためのものです。指定しない場合、アイコンはデフォルトでファビコンになります。

[
  {
    "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."
}

次の点に注意してください。

  • authorsとcontributorsの順序に意味はなく、重要ではありません。