كتابة تعليقات المحلّل

يقدّم هذا المستند معلومات وإرشادات حول كيفية كتابة التعليقات التي ينتجها المحلّل.

المحتويات

تُخزَّن محتويات تعليقات المحلّل كمستند Markdown في مستودع exercism/website-copy. تحتوي التعليقات على معرّف إشاري على شكل سلسلة نصية بالصيغة <track-slug>.<exercise-slug>.<comment-slug>، يرتبط بمستند Markdown محدّد في مستودع website-copy.

على سبيل المثال، يشير ruby.two-fer.string-interpolation إلى https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md.

الصياغة

• تجنّب التعليقات المطوّلة بلا داعٍ. كن موجزًا.
• كن محايدًا في ملاحظاتك؛ وتجنّب العبارات المشحونة والتعميمات.
• اجعل التوصية صريحة.
• حيث أمكن، ضع التوصية أولًا ثم الشرح.
• تجنّب "أنا" و"نحن" وما شابه، لأن الروبوت ليس شخصًا.
• تجنّب "أنت" و"الكود الخاص بك"، لأنه قد يبدو أحيانًا كحكم على الشخص لا على الكود.
• تجنّب كلمات مثل "مجرد" و"ببساطة" و"من الواضح"، فقد تبدو متعالية: إذا كان التعليق ضروريًا، فمن الواضح أنه لم يكن واضحًا.
• تجنّب افتراض ما يعرفه الناس وما لا يعرفونه. الاستثناء الوحيد هو المعرفة المكتسبة من التمارين الأساسية التي أُكملت بالفعل. تجنّب عبارات مثل "كما تعلم" و"كما تتذكر" و"كما تعلمت" و"الآن بعد أن فهمنا جميعًا س"، لأنه حتى إن قيل شيء ما، فليس بالضرورة أن الشخص قد فهمه.

التوجيهات

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

التمارين الأولى

في التمارين الأولى من مسار ما، يكون ما يلي بالغ الأهمية:

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

أمثلة

في JavaScript، كتب طالب ثابتًا على المستوى الأعلى باستخدام let.

<!-- not following these guidelines -->

As you know, everyone uses const, you shouldn't use let or var.

هذا التعليق لا يتبع هذه الإرشادات للأسباب التالية:

• الفعل يأتي بعد "الشرح".
• "كما تعلم": لا نعرف إن كان الطالب يعلم ذلك.
• "لا ينبغي أن": لا تحتاج إلى "أنت" لتصوغ هذه العبارة.
• "الجميع يستخدم const": هذا غير صحيح _و_قد يجعل الطالب يشعر بأنه ارتكب خطأً فادحًا.
• يفتقر إلى شرح فعلي لـ_سبب_ تقديم النصيحة.

<!-- better -->

Prefer `const` and `let` over `var`. The `const` declaration stops a variable
from being accidentally reassigned, which provides safety, and reduces
cognitive load for someone reading the code. [This article](https://medium.com/javascript-scene/javascript-es6-var-let-or-const-ba58b8dcde75)
explains the difference between the three.

في Go، أنشأ طالب خطأً مخصّصًا بدل استخدام الأخطاء المدمجة:

<!-- not following these guidelines -->

I see you are creating a custom `error`. This is perfectly fine! If you did not
know about `errors.New` and `fmt.Errorf` have a look at them as they are much
simpler ways to create an error. Custom errors are helpful if you want to check
if an error is of a certain type later.

هذا التعليق لا يتبع هذه الإرشادات للأسباب التالية:

• "أرى": المحلّل ليس شخصًا، فتجنّب "أنا".
• "هذا مقبول تمامًا!": يبدو أنه ليس كذلك، وإلا لما كان التطمين ضروريًا. يمكن على الأرجح حذف هذه العبارة كليًا؛ وإذا أردت تقديم نصيحة عامة عن وجود شيء ما، يمكنك قول ذلك بالضبط: "هناك طريقة بديلة، صحيحة بالقدر نفسه، لفعل س هي ص."
• "إذا لم تكن تعرف عن": احذف هذه العبارة المطوّلة أكثر من اللازم.

<!-- better -->

A custom `error` is typically used to provide custom behavior, or to distinguish
on type later. For simpler cases, it's more common to rely on `errors.New` or
`fmt.Errorf`. This [in-depth article](https://golangbot.com/custom-errors/) about
custom errors might be interesting.

التكامل المستمر (CI)

لأن التعليقات لا تعيش في المستودع نفسه الذي يعيش فيه المحلّل، ينبغي أن يكون لكل محلّل تكامل مستمر (CI) يتحقق من أن التعليقات المستخدمة في ذلك المحلّل تحديدًا (تلك التي قد تصبح مخرجات)، هي تعليقات على فرع main في مستودع exercism/website-copy.

وقت كتابة هذه السطور، تتابع هذه المشكلة حالة أي تعميم لهذا التكامل المستمر (CI)، إن وُجد.