المفاهيم

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

البيانات الوصفية

تُعرَّف البيانات الوصفية للمفهوم في المفتاح concepts في ملف config.json. وتُحدِّد هذه البيانات الوصفية معرّف UUID وslug للمفهوم وغير ذلك.

مثال

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

الملفات

لكل مفهوم مجلده الخاص داخل مجلد concepts في المسار. ويجب أن يتطابق اسم مجلد المفهوم مع خاصية slug الخاصة بالمفهوم، كما هي معرّفة في ملف config.json.

يحتوي المفهوم على نوعين من الملفات:

ملفات التوثيق

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

• about.md: يقدّم معلومات عن المفهوم للطالب الذي أكمل تمرين المفاهيم المقابل، ليتعلّم منها ويعود إليها لاحقًا (مطلوب)
• introduction.md: يقدّم مقدمة موجزة للطالب الذي لم يكمل بعد تمرين المفاهيم المقابل (مطلوب)
• links.json: يقدّم روابط مفيدة توفر مزيدًا من القراءة أو المعلومات عن مفهوم ما (مطلوب)

ملفات البيانات الوصفية

لا تُعرض هذه الملفات على الطالب، وإنما تُستخدم لتعريف البيانات الوصفية للمفهوم.

• .meta/config.json: يحتوي على معلومات وصفية عن المفهوم (مطلوب)

مثال

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

الملف: about.md

الغرض: تقديم معلومات أكثر تفصيلًا عن المفهوم للطالب الذي أكمل تمرين المفاهيم المقابل، ليتعلّم منها ويعود إليها لاحقًا.

التوفر: مطلوب

بعد إكمال تمرين المفاهيم المقابل (المعروف أيضًا بأنه "تعلّم" المفهوم)، ستعرض صفحة المفهوم محتويات ملف about.md بدلًا من ملف introduction.md. وينبغي أن يقدّم ملف about.md للطلاب معلومات شاملة عمّا يحتاجون معرفته لإتقان المفهوم. وعلى الأقل، ينبغي أن يحتوي هذا الملف على كل المعلومات التي تُقدَّم في مستند introduction.md الخاص بالمفهوم.

إذا قدّم المفهوم صياغة جديدة، فينبغي تضمين أمثلة على تلك الصياغة. ولا ينبغي أن يضطر الطالب إلى تتبّع الكثير من الروابط لاكتساب المعرفة التي يحاول الملف إيصالها. وبدلًا من ذلك، ينبغي أن يحتوي about.md على معلومات كافية ليكون مفهومًا في سياقه.

لا يقتصر ملف about.md على نطاق تمرين المفاهيم المقابل. فقد يتطلب المحتوى معرفة بمفاهيم أخرى ستُقدَّم لاحقًا. وإذا ذُكرت مفاهيم أخرى، فينبغي الربط بمقدماتها الخاصة (راجع الربط الداخلي للتفاصيل).

وفيما يلي بعض الأمثلة على ما يمكن تغطيته.

• الاستخدامات الشائعة للمفهوم
• الأخطاء الشائعة عند استخدام المفهوم (مثل عدم مراعاة أمان الخيوط)
• القيود على الاستخدام التي قد تُفاجئ المبرمج غير المتوقّع لها
• الأساليب البديلة التي تتناولها مفاهيم أخرى (مثلًا، قد يشير مفهوم الاستدعاء الذاتي إلى أن مفهوم الدوال ذات الرتبة الأعلى يقدّم أسلوبًا بديلًا لمشكلات مشابهة)
• التنازلات التي تُجرى لتسهيل التعلّم أو لملاءمة بيئة Exercism، مثل وجود أصناف متعددة في ملف واحد
• الميزات المشابهة التي قد يختلط بها المفهوم
• خصائص الأداء واستهلاك الذاكرة، عندما تكون اعتبارًا شائعًا في تلك اللغة
• لا تُشِر إلى تمرين في النص، لأن هذا الملف يُعرض خارج سياق التمرين.

ليس الهدف من ملف 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;
```

الملف: links.json

الغرض: تقديم روابط مفيدة توفر مزيدًا من القراءة أو المعلومات عن مفهوم ما.

التوفر: مطلوب

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

يجب أن يحتوي كل رابط على الحقول التالية:

• url: عنوان URL الذي يرتبط به.
• description: وصف للرابط، يُعرض كنص الرابط.

ويمكن أن تحتوي الروابط أيضًا، بشكل اختياري، على حقل icon_url الذي يمكن استخدامه لتخصيص الأيقونة المعروضة عند عرض الرابط. وإذا لم يُحدَّد، فستكون الأيقونة الافتراضية هي favicon.

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

لاحظ ما يلي:

• ترتيب المؤلفين والمساهمين ليس مهمًا وليس له أي معنى.