共用檔案


有些文件檔案同時適用於概念練習與實作練習。這些跨練習的檔案位於該 track 的exercises/shared/.docs目錄中:

  • debug.md:說明在瀏覽器中寫程式的學生要如何仍然進行「除錯」(選填)
  • help.md:包含這個 track 專屬的取得協助說明(必填)
  • representations.md:說明系統會對解法套用哪些正規化,以建立它的 representation(選填)
  • tests.md:包含這個 track 專屬的測試執行說明(必填)

呈現文件說明了這些檔案如何用來向學生呈現內容。


檔案:debug.md

**用途:**說明在瀏覽器中寫程式的學生要如何仍然進行「除錯」

**是否必填:**選填

瀏覽器內的編輯器沒有任何內建的除錯支援。如果該 track 的測試執行器支援擷取主控台輸出,學生仍然可以進行某種形式的「除錯」,這份文件說明了該怎麼做。

這個檔案的內容_只_會顯示在線上編輯器;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

**用途:**說明學生可以如何取得協助

**是否必填:**必填

說明學生可以如何取得協助,且特別針對這個 track(而非整個 Exercism)。

這個檔案的內容_只_會被 CLI 使用,它會將它納入 HELP.md 檔案中。

說明應該簡短扼要。

你可以連結到 Gitter 頻道、論壇或郵件論壇等資源:任何能幫助學生擺脫困境的內容都可以。

這份文件中的連結可以與 docs/LEARNING.md 或 docs/RESOURCES.md 中的連結重疊。

這份文件不應連結到整個 Exercism 通用(與 track 無關)的協助資源,因為那些資源會自動包含在 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

**用途:**說明系統會對解法套用哪些正規化,以建立它的 representation

**是否必填:**選填

當某個 track 實作了 representer 之後,每個提交的解法都會為它建立一份 representation。

這份文件應該列出 representer 對解法套用的所有正規化。

這能在導師加入 representation 註解時提供協助。

範例

# 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

如果你的 track 有 docs/REPRESENTER_NORMALIZATIONS.md 檔案,我們建議把各項正規化連結到該檔案中對應的段落。

檔案:tests.md

**用途:**包含這個 track 專屬的測試執行說明

**是否必填:**必填

說明如何為這個特定練習執行測試。

這個檔案的內容_只_會被 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)來覆寫 track 專屬檔案。這應該很少需要(甚至根本不需要)。