共有ファイル

一部のドキュメントファイルは、コンセプト演習とプラクティス演習の両方に当てはまります。これらの演習をまたいで共通するファイルは、トラックのexercises/shared/.docsディレクトリに置きます。

  • debug.md: ブラウザーでコードを書いている学習者が、それでも「デバッグ」を行う方法を説明します（任意）
  • help.md: ヘルプの受け方に関するトラック固有の説明が含まれます（必須）
  • representations.md: 解答からその表現を作成するために、どのような正規化が適用されるかを説明します（任意）
  • tests.md: テストの実行方法に関するトラック固有の説明が含まれます（必須）

プレゼンテーションドキュメントでは、これらのファイルを使って学習者にコンテンツをどのように提示するかを説明しています。

ファイル: debug.md

目的: ブラウザーでコードを書いている学習者が、それでも「デバッグ」を行う方法を説明します

有無: 任意

ブラウザー内のエディターには、デバッグを支援する機能が組み込まれていません。トラックのテストランナーがコンソール出力の取り込みに対応していれば、学習者でも何らかの形で「デバッグ」を行うことができ、このドキュメントではその方法を説明します。

このファイルの内容は_オンラインエディターでのみ_表示されます。CLIはこのファイルを無視します。

例

# Debug

To help with debugging, you can use the fact that any [console output](https://www.programiz.com/csharp-programming/basic-input-output) will be shown in the test results window. You can write to the console using:

```csharp
Console.WriteLine("Debug message");
```

ファイル: help.md

目的: 学習者がヘルプを受ける方法を説明します

有無: 必須

学習者がヘルプを受ける方法を、このトラックに固有の内容（Exercism全体ではなく）として説明します。

このファイルの内容は_CLIでのみ_使われ、CLIがこれをHELP.mdファイルに含めます。

説明は短く、要点を押さえたものにしましょう。

Gitterのチャンネル、フォーラム、メーリングリストなど、学習者が行き詰まりから抜け出す助けになるものへのリンクを載せるとよいでしょう。

このドキュメントのリンクは、docs/LEARNING.mdやdocs/RESOURCES.mdのリンクと重複してもかまいません。

このドキュメントには、Exercism全体で共通の（トラックに依存しない）ヘルプリソースへのリンクを載せないでください。そうしたリソースはHELP.mdファイルに自動的に含まれるためです。

例

# Help

To get help if you're having trouble, you can use one of the following resources:

- [Kotlin Documentation](https://kotlinlang.org/docs/reference/)
- [Kotlin Forums](https://discuss.kotlinlang.org/)
- [Kotlin Slack Channel](https://kotlinlang.slack.com/): [get invite here](https://slack.kotlinlang.org/)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/kotlin)
- [Kotlin Subreddit](https://www.reddit.com/r/kotlin)

ファイル: representations.md

目的: 解答からその表現を作成するために、どのような正規化が適用されるかを説明します

有無: 任意

トラックがrepresenterを実装している場合、提出された解答ごとに、その解答の表現が作成されます。

このドキュメントには、representerが解答に適用するすべての正規化を一覧にします。

これは、メンターが表現へのコメントを追加するときに役立ちます。

例

# Representations

The representer applies the following normalizations:

- All comments are removed
- All import declarations are removed
- The code is formatted
- Identifiers are normalized to a placeholder value

トラックにdocs/REPRESENTER_NORMALIZATIONS.mdファイルがある場合は、各正規化をそのファイル内の対応するセクションにリンクすることをおすすめします。

ファイル: tests.md

目的: テストの実行方法に関するトラック固有の説明が含まれます

有無: 必須

この特定の演習のテストを実行する方法を説明します。

このファイルの内容は_CLIでのみ_使われ、CLIがこれをHELP.mdファイルに含めます。

説明は短く、要点を押さえたものにしましょう。

docs/TESTS.mdファイルには、テストの実行方法について、より詳しい説明を載せることができます。

例

# Tests

To run the tests, run the command `dotnet test` from within the exercise directory.

上書き

注: これはまだ実装されていません

演習側で、その演習の.docsディレクトリに同じ名前のファイル（例：.docs/debug.md）を作成すると、トラック固有のファイルを上書きできます。この必要があるのはごくまれな場合だけです（まったくないかもしれません）。