有些文件檔案同時適用於概念練習與實作練習。這些跨練習的檔案位於該 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 專屬檔案。這應該很少需要(甚至根本不需要)。