يعمل هذا المستند دليلَ أسلوبٍ للغة والصياغة المستخدمتين في التمارين.
التطبيق
ينبغي اتباع هذه القواعد في جميع التمارين.
ويمكن تحديث الأوصاف وحالات الاختبار الموجودة لتتوافق معها دون الحاجة إلى حالات اختبار «بديلة».
الاتساق داخل التمرين
هناك بعض المصطلحات التي لها أكثر من كتابة صحيحة (مثل «lower case» مقابل «lowercase»).
وحيث لم يُتفق على أسلوب موحّد داخل هذا المستند، يجب أن تكون هذه المصطلحات متسقة داخل التمرين الواحد.
الاستثناءات
يجوز أن تخرج التمارين عن هذه القواعد إذا كان هناك توافق عام بين القائمين على الصيانة على أن ذلك معقول.
على سبيل المثال، قد يختار تمرين عن التحويل بين وحدات مختلفة ألّا يستخدم قياسات النظام الدولي للوحدات.
اللغة
ينبغي كتابة كل المحتوى بالإنجليزية الأمريكية، وهي تختلف عن الإنجليزية البريطانية في عدة نواحٍ. وقد تُجرى ترجمات أخرى في المستقبل، لكن لغة Exercism «الرسمية» هي الإنجليزية الأمريكية.
القياسات
يجب أن تكون جميع وحدات القياس وحدات النظام الدولي للوحدات أو مشتقة منه.
الاختصارات والكلمات المختصرة والاختصارات الحرفية
غالبًا ما تكون الاختصارات والكلمات المختصرة والاختصارات الحرفية أصعب في الفهم من غيرها من صيغ التعبير، وقد تُنفّر الأشخاص الذين يحاولون التعلّم.
العديد من الاختصارات مصطلحات تقنية. تجنّب المصطلحات التقنية قدر الإمكان باستخدام صياغة بديلة. لا تستخدم الاختصارات إلا في إحدى الحالتين:
- أن يكون المصطلح المختصر أشهر من صيغته الكاملة
- أن يصبح النص مطوّلًا بشكل مفرط من دون الاختصار
عند استخدام الاختصارات، اشرح دائمًا معنى المصطلح عند أول استخدام له. وسيشمل ذلك غالبًا، وليس دائمًا، كتابة الاختصار كاملًا. ونادرًا ما يكون كتابة الاختصار كاملًا وحده كافيًا.
وفيما يلي بعض الأمثلة على القواعد:
- فضّل «if I recall correctly» على «IIRC»
- فضّل «as far as I know» على «AFAIK»
- فضّل «queue» على «FIFO» و«stack» على «FILO»
- بدلًا من وصف واجهة بأنها «RESTful»، صِف خصائصها المحددة
- إذا كان لا بد من استخدام «CRUD»، فاشرح أنها اختصار لـ Create وRead وUpdate وDelete، وأنها الإجراءات الأساسية في قواعد البيانات القياسية
وفيما يلي بعض الأمثلة على الاستخدام الجيد:
- «HyperText Markup Language (HTML) is the language used to describe document structure and content on the web» (مكتوبة كاملة ومشروحة)
- «DNA, a set of chemical instructions that influence how our bodies are constructed» (لم تُكتب DNA كاملة لأن «deoxyribonucleic acid» من غير المرجح أن تساعد في شرح معنى DNA لجمهورنا)
- «NASA, the United States' space agency, launched the Mariner 2 space probe in...» (لم تُكتب NASA كاملة لأن «National Aerospace and Space Administration» أشهر بكثير باختصارها من اسمها الكامل)
- «The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV» (عرّف DMV عند أول استخدام لها)
القواعد النحوية
فاصلة أوكسفورد
استخدم «فاصلة أوكسفورد» (المعروفة أيضًا بالفاصلة التسلسلية) في القوائم. على سبيل المثال، بدلًا من «I love my parents, Lady Gaga and Humpty Dumpty»، اكتب «I love my parents, Lady Gaga, and Humpty Dumpty». وقد تعجبك أيضًا هذه الصورة كشرح.
الاستثناءات
هناك بعض الاختصارات نعتبرها شائعة ومفيدة وغير تقنية بما يكفي، ولذلك قرّرنا السماح بها:
-
e.g. or eg
-
i.e. or ie
-
etc. or etc
docs
ينبغي استخدام الصيغ المدمجة (مثل «won't» و«I'm» و«that's») باعتدال، أو عدم استخدامها إطلاقًا، في أوصاف التمارين، لكنها غير مقيّدة في بقية النصوص حول الموقع (مثل نصوص الموقع، والإرشاد).
تذكر العديد من أدلة أسلوب الإنجليزية الأمريكية أن الاختصارين «i.e.» و«e.g.» ينبغي أن يتبعهما فاصلة (انظر، على سبيل المثال، هذا الموضوع على StackExchange). وهذا مسموح به، لكنه غير مطلوب في النصوص على Exercism.
اختيار الكلمات
المصطلحات الرياضية والمصطلحات التقنية
في أي موضع تُستخدم فيه مصطلحات رياضية، ينبغي شرحها أو استبدالها بمصطلحات تتطلب معرفة تخصصية أقل.
أمثلة:
- بدلًا من استخدام «natural numbers»، ينبغي أن نستخدم «positive whole numbers».
- وإذا أردنا استخدام عبارة «rational numbers»، فيجب شرحها في مقدمة التمرين.
- وبدلًا من استخدام كلمة range (التي قد يكون لها معانٍ مختلفة في سياقات مختلفة)، استخدم «x < ? < y (greater than x and less than y)».
- وبدلًا من استخدام «esoteric terms»، استخدم عبارة «terms not understood by the majority of people».
الكود
ينبغي تنسيق كل الكود باستمرار وفقًا لأعراف الأسلوب في مساره. وحين يكون ذلك ممكنًا، ينبغي أن تطابق هذه الأعراف على مستوى المسار أعراف الأسلوب المفضّلة في اللغة.
