مقدمة
رأينا في التمرين السابق أن هناك أسلوبين لكتابة التعليقات في Go: التعليقات أحادية السطر التي يسبقها //، وكتل التعليقات متعددة الأسطر التي يُحاط بها بـ /* و*/.
تعليقات التوثيق
في Go، تلعب التعليقات دورًا مهمًا في توثيق الكود.
ويستخدمها الأمر godoc، الذي يستخرج هذه التعليقات لإنشاء توثيق عن حزم Go.
وينبغي أن يكون التعليق التوثيقي جملة كاملة تبدأ باسم الشيء الموصوف وتنتهي بنقطة.
وينبغي أن تسبق التعليقات الحزم وكذلك المعرّفات المصدَّرة، ومنها الدوال والطرق ومتغيرات الحزمة والثوابت وstruct، وستتعلم المزيد عنها في التمارين القادمة.
قد يبدو متغير على مستوى الحزمة هكذا:
// TemperatureCelsius represents a certain temperature in degrees Celsius.
var TemperatureCelsius float64
تعليقات الحزمة
ينبغي كتابة تعليقات الحزمة مباشرةً قبل جملة الحزمة (package x) وأن تبدأ بـ Package x ... هكذا:
// Package kelvin provides tools to convert
// temperatures to and from Kelvin.
package kelvin
تعليقات الدوال
ينبغي كتابة تعليق الدالة مباشرةً قبل تعريف الدالة.
وينبغي أن يكون جملة كاملة تبدأ باسم الدالة.
على سبيل المثال، ينبغي أن يأخذ التعليق المصدَّر للدالة Calculate الصيغة Calculate ....
وينبغي أيضًا أن يوضّح ما الوسائط التي تأخذها الدالة، وما الذي تفعله بها، وما تعنيه قيم الإرجاع، وأن ينتهي بنقطة):
// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
return 0
}
التعليمات
Goblinocus بلد يتعامل مع توقعات الطقس بجدية بالغة. ولأنك مطوّر مسؤول وبارع وذو سمعة طيبة، طلبوا منك كتابة برنامج يستطيع التنبؤ بحالة الطقس الحالية في مدن مختلفة في Goblinocus. لكنك كنت مشغولًا في ذلك الوقت، فطلبت من أحد أصدقائك أن يقوم بالمهمة بدلًا منك. وبعد فترة، تواصل معك رئيس Goblinocus وقال إنه لا يفهم كود صديقك. وعندما تفحّصت الكود، اكتشفت أن صديقك لم يتصرف كمبرمج مسؤول، فليس في الكود أي تعليقات. لذلك تشعر بأن من واجبك توضيح البرنامج حتى يتمكن العفاريت من فهمه أيضًا.
1. وثّق package weather
بما أن العفاريت ليسوا أذكياء مثلك، فقد نسوا ما الذي ينبغي أن تفعله الحزمة من أجلهم. من فضلك اكتب تعليقًا لـ package weather يصف محتواه. ينبغي أن يقدّم تعليق الحزمة الحزمةَ ويزوّد القارئ بمعلومات تتعلق بالحزمة ككل.
2. وثّق المتغيرين CurrentCondition وCurrentLocation
رئيس Goblinocus مصاب بقليل من جنون الارتياب، ويخشى أن تُستخدم متغيرات بلا تعليقات لتدمير بلده. من فضلك وضّح استخدام متغيرَي الحزمة CurrentCondition وCurrentLocation وطمئن الرئيس. ينبغي أن يخبر ذلك أي مستخدم للحزمة بالمعلومات التي تخزّنها المتغيرات، وبما يمكنه فعله بها.
3. وثّق الدالة Forecast()
يريد مشغّلو التوقعات الجوية في Goblinocus معرفة ما الذي تفعله الدالة Forecast() (لكن لا تخبرهم كيف تعمل، لأنهم للأسف سيزدادون ارتباكًا). من فضلك اكتب تعليقًا لهذه الدالة يصف ما الذي تفعله الدالة، لا كيف تفعله.
تمرين تعلّمي
