توثيق Go: كتابة كود يتحدث عن نفسه

لماذا التوثيق في Go هو قوة خارقة، وليس واجبًا مملًا

تخيل: تفتح مشروع Go لشخص آخر، ولا تجد أي تعليق. الدوال تُسمى f1، f2، والهياكل تُسمى Data و MoreData. هل هذا مألوف؟ إذا كان الأمر كذلك، فأنت تعلم كيف يتحول الحماس بسرعة إلى رغبة في إغلاق المستودع.

Go هي لغة تعشق البساطة والوضوح. ولكن حتى أنظف كود لا يتحدث دائمًا عن نفسه. التوثيق الجيد في Go ليس مجرد "لفتة لطيفة" للزملاء. إنها أداة احترافية تعمل على:

\n
• تسريع عملية دمج المطورين الجدد؛
\n
• المساعدة في تجنب الأخطاء (هل تتذكر أن التعليقات يمكن أن تنقذ من الاستخدام الخاطئ لـ API؟)؛
• إنشاء صفحات جميلة تلقائيًا على pkg.go.dev؛
• رفع جودة الكود (حاول كتابة تعليق لدالة سيئة - ستجد نفسك ترغب في إعادة كتابتها).

في هذه المقالة، سنستعرض أفضل ممارسات توثيق مشاريع Go. من القواعد الأساسية لـ godoc إلى أمثلة واقعية يمكنك تطبيقها اليوم. هيا بنا!

فلسفة التوثيق في Go: كلمات أقل - معنى أكثر

Go ليست Java أو Python. لا أحد هنا يكتب توثيقًا متعدد الصفحات مثل Javadoc أو docstrings بطول 20 سطرًا. فلسفة Go بسيطة: وثق السلوك، وليس التنفيذ.

في الدليل الرسمي Effective Go، يُذكر بوضوح: يجب أن تصف التعليقات ماذا يفعل الكود، وليس كيف. إذا كان كودك معقدًا لدرجة أنه لا يمكن الاستغناء عن شرح الخوارزمية - فربما يجب تبسيطه.

المبادئ الأساسية:

\n
• التعليق هو جملة. ابدأ باسم الدالة أو النوع. // Calculate returns the result of the calculation. - ممتاز. // This function calculates... - نفقد التركيز.
• اكتب بالإنجليزية. Go هي لغة دولية، والتوثيق بالإنجليزية هو المعيار الفعلي. ولكن إذا كان مشروعك مخصصًا لفريق ناطق بالعربية، يمكنك الكتابة بالعربية. الأهم هو الاتساق.
• لا تشرح الواضح. // SetName sets the name - عديم الفائدة. الأفضل: // SetName updates the user's display name. Must be called before Save.

Godoc: صديقك المفضل وموثقك التلقائي

تأتي Go مع أداة مدمجة تسمى godoc. تقوم بتحليل التعليقات مباشرة من الكود وإنشاء توثيق HTML. هذا يعني أن توثيقك يعيش بجانب الكود - ويتم تحديثه في نفس الوقت.

كيف يعمل هذا؟ بسيط جدًا. اكتب تعليقًا مباشرة قبل الكيان المُصدر (دالة، نوع، هيكل، ثابت) - وسيقوم godoc بالتقاطه.

مثال لحزمة أساسية:

// Package calculator provides basic arithmetic operations.\npackage calculator\n\n// Add returns the sum of two integers.\nfunc Add(a, b int) int {\n    return a + b\n}\n\n// Subtract returns the difference of two integers.\nfunc Subtract(a, b int) int {\n    return a - b\n}

الآن قم بتشغيل godoc -http :8080 وافتح المتصفح. سترى صفحة جميلة مع وصف للحزمة وكل دالة. سحر!

قواعد الذوق الرفيع لـ godoc

\n
• قم دائمًا بالتعليق على الحزمة. تعليق الحزمة هو أول ما يراه المستخدم. يجب أن يصف الغرض من الحزمة، ومن الأفضل أن يحتوي على مثال استخدام.
• لا تنسَ الأنواع والهياكل. إذا كان للهيكل حقول غير واضحة من الاسم، قم بتوثيقها أيضًا.
• استخدم سطرًا فارغًا. يعتبر godoc الفقرة الأولى كوصف مختصر، وكل ما تبقى كتفاصيل. افصل بينهما بسطر فارغ.

// User repre