الملفات المشتركة

تنطبق بعض ملفات التوثيق على كلٍّ من التمارين المفاهيمية والتمارين التطبيقية. توجد هذه الملفات المشتركة بين التمارين داخل مجلد المسار exercises/shared/.docs:

  • debug.md: يشرح كيف يمكن للطالب الذي يكتب الكود في المتصفح أن يقوم بتصحيح الأخطاء (اختياري)
  • help.md: يحتوي على تعليمات خاصة بالمسار حول كيفية الحصول على المساعدة (مطلوب)
  • representations.md: يشرح عمليات التسوية التي تُطبَّق على الحل لإنشاء تمثيله (اختياري)
  • tests.md: يحتوي على تعليمات خاصة بالمسار حول كيفية تشغيل الاختبارات (مطلوب)

يوضح مستند العرض كيف تُستخدم هذه الملفات لعرض المحتوى على الطالب.

الملف: debug.md

الغرض: شرح كيف يمكن للطالب الذي يكتب الكود في المتصفح أن يقوم بتصحيح الأخطاء

التواجد: اختياري

لا يحتوي المحرر داخل المتصفح على أي دعم مدمج لتصحيح الأخطاء. إذا كان مشغّل الاختبارات في المسار يدعم التقاط مخرجات وحدة التحكم، فيمكن للطالب حينها القيام بشكل من أشكال تصحيح الأخطاء، ويشرح هذا المستند كيفية القيام بذلك.

يُعرض محتوى هذا الملف في المحرر عبر الإنترنت فقط؛ وستتجاهل واجهة سطر الأوامر هذا الملف.

مثال

# 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 ككل).

تُستخدم محتويات هذا الملف بواسطة واجهة سطر الأوامر فقط، وهي تضمّنه في ملف 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

الغرض: يشرح عمليات التسوية التي تُطبَّق على الحل لإنشاء تمثيله

التواجد: اختياري

عندما ينفّذ مسار ما مُمثِّلًا، سيُنشأ لكل حل مُرسَل تمثيل خاص به.

ينبغي أن يسرد هذا المستند جميع عمليات التسوية التي يطبّقها المُمثِّل على الحل.

يساعد ذلك المرشد عند إضافة تعليقات التمثيل.

مثال

# 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

الغرض: يحتوي على تعليمات خاصة بالمسار حول كيفية تشغيل الاختبارات

التواجد: مطلوب

صِف كيفية تشغيل الاختبارات لهذا التمرين تحديدًا.

تُستخدم محتويات هذا الملف بواسطة واجهة سطر الأوامر فقط، وهي تضمّنه في ملف HELP.md.

يجب أن تكون التعليمات قصيرة ومباشرة.

يمكن أن يحتوي ملف docs/TESTS.md على وصف أكثر تفصيلًا لكيفية تشغيل الاختبارات.

مثال

# Tests

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

الكتابة فوق الملفات

ملاحظة: هذا غير مُنفَّذ بعد

يمكن للتمارين أن تكتب فوق الملفات الخاصة بالمسار من خلال إنشاء ملف بالاسم نفسه في مجلد .docs الخاص بالتمرين (مثل .docs/debug.md). ونادرًا ما يكون هذا مطلوبًا (إن كان مطلوبًا أصلًا).