عندما تفكر في البرمجة ، فمن الطبيعي أن تركز على موضوعات مثل اللغات والخوارزميات وتصحيح الأخطاء. لكن التوثيق الفني يمكن أن يكون بنفس الأهمية للحصول على المعلومات الصحيحة.
بدون توثيق جيد ، يمكن أن تتأثر قابلية إعادة استخدام الكود. يمكن للمستخدمين الجدد في قاعدة الرموز أن يضيعوا أو يصابوا بالإحباط بسهولة إذا لم تكن الوثائق جاهزة للخدش. ليس من المهم فقط فهم ما يفعله البرنامج ، ولكن كيف - أو حتى لماذا - يفعله.
تساعد الحزم مثل Pydoc for Python و Javadoc for Java عن طريق أتمتة جزء من العملية. تقوم أداة Godoc بنفس الشيء مع Go.
ما هو جودوك؟
Godoc عبارة عن حزمة Go تتيح لك إنشاء وإدارة واستخدام وثائق Go في "طريقة Go". طريقة Go هي مجموعة من المبادئ ، بصفتك مبرمج Go ، يجب عليك اتباعها لتحسين جودة الكود.
باستخدام Godoc ، يمكنك بسهولة قراءة وثائق ورموز المطورين الآخرين. يمكنك أيضًا أتمتة إنشاء الوثائق الخاصة بك ونشرها باستخدام Godoc.
Godoc مشابه لـ جافادوك ، وثيقة الشفرة لجافا. كلاهما يستخدم التعليقات والتعليمات البرمجية في الوحدات النمطية لإنشاء الوثائق. وتقوم كلتا الأداتين ببناء تلك الوثائق بتنسيق HTML بحيث يمكنك عرضها في المستعرض.
الشروع في العمل مع Godoc
استخدام Godoc سهل. للبدء ، قم بتثبيت حزمة Godoc من موقع golang باستخدام هذا الأمر:
يذهب احصل على golang.org/x/tools/cmd/godoc
سيؤدي تشغيل هذا الأمر إلى تثبيت Godoc في مساحة العمل المحددة الخاصة بك. بمجرد اكتماله ، يجب أن تكون قادرًا على تشغيل ملف جودوك الأمر في المحطة. إذا كانت هناك أية أخطاء في التثبيت ، فحاول تحديث Go إلى إصدار حديث.
يبحث Godoc عن تعليقات فردية ومتعددة الأسطر لتضمينها في الوثائق التي ينشئها.
تأكد من تنسيق الكود طريقة Go ، كما هو موضح في المنشور الفعال Go بواسطة فريق Go للحصول على أفضل النتائج.
فيما يلي مثال على استخدام أسلوب التعليقات أحادية السطر C ++:
// المستخدم هو نموذج هيكلي يحتوي على
يكتب المستعمل هيكل {
}
يمكنك أيضًا استخدام تعليقات المجموعة ذات النمط C:
/*
المستخدم هو هيكل بيانات مخصصيمكنك تضمين أي نص هنا وسيقوم خادم Godoc بتنسيقه عند تشغيله.
*/
يكتب المستعمل هيكل {
}
في التعليقات أعلاه ، يبدأ "المستخدم" الجمل لأن التعليق يصف ما يفعله هيكل المستخدم. هذا هو أحد الموضوعات العديدة التي يناقشها Go way. يعد بدء جمل التوثيق باسم مفيد أمرًا بالغ الأهمية لأن الجملة الأولى تظهر في قائمة الحزم.
تشغيل خادم Godoc
بمجرد قيامك بالتعليق على التعليمات البرمجية الخاصة بك ، يمكنك تشغيل ملف جودوك الأمر في المحطة الطرفية ، من دليل كود مشروعك.
تقليديًا ، يستخدم مطورو Go المنفذ 6060 لاستضافة الوثائق. هذا هو الأمر لتشغيل خادم Godoc على هذا المنفذ:
Godoc -http =: 6060
يستضيف الأمر أعلاه وثائق التعليمات البرمجية الخاصة بك على المضيف المحلي أو 127.0.0.1. لا يجب أن يكون المنفذ 6060 ؛ سوف يعمل godoc على أي ميناء غير مأهول. ومع ذلك ، فمن الأفضل دائمًا اتباع اصطلاحات توثيق Go.
بمجرد تشغيل الأمر ، يمكنك عرض الوثائق الخاصة بك في المستعرض من خلال زيارة المضيف المحلي: 6060. يعتمد الوقت الذي يستغرقه Godoc لإنشاء وثائقك على حجمها ودرجة تعقيدها.
يلتزم الكود أدناه بطريقة Go ، في هذه الحالة باستخدام تعليقات من سطر واحد.
// اسم الحزمة
حزمة المستعمل// fmt مسؤول عن التنسيق
يستورد (
"FMT"
)// المستخدم عبارة عن هيكل من البيانات البشرية
يكتب المستعمل هيكل {
سن int
اسم سلسلة
}funcرئيسي() {
// الإنسان هو تهيئة لبنية المستخدم
الإنسان: = المستخدم {
سن: 0,
الاسم: "شخص" ،
}FMT. Println (الإنسان. التكلم())
}
// الحديث هو أسلوب من بنية المستخدم
func(مستخدم جهاز الاستقبال)التكلم()سلسلة {
إرجاع "كل مستخدم يمكنه أن يقول شيئًا ما!"
}
إذا قمت بتشغيل Godoc على وحدة التعليمات البرمجية أعلاه ، فسترى الإخراج يبدو مثل هذا:
لاحظ أنه بتنسيق مألوف ، مشابه لما ستجده على موقع التوثيق الرسمي Go.
يستخدم Godoc التعليق الذي يسبق إعلان الحزمة كـ ملخص. تأكد من أن هذا التعليق يصف ما يفعله برنامجك.
ال فِهرِس يحتوي على روابط للإعلانات والطرق بحيث يمكنك الانتقال إليها بسرعة.
يوفر Godoc أيضًا وظائف لعرض الكود المصدري الذي يتكون من الحزمة في ملف حزم الملفات الجزء.
تحسين التوثيق الخاص بك باستخدام Godoc
يمكنك تضمين أكثر من مجرد نص عادي في وثائق Godoc الخاصة بك. يمكنك إضافة عناوين URL التي سيقوم Godoc بإنشاء روابط لها وتنظيم تعليقاتك في فقرات.
إذا كنت تريد الارتباط بمصدر ، فاكتب عنوان URL في تعليقك ، وسوف يتعرف عليه Godoc ويضيف رابطًا. بالنسبة للفقرات ، اترك سطر تعليق فارغًا.
// الحزمة الرئيسية
حزمة رئيسي// يمثل المستند مستندًا عاديًا.
//
// رابط ل https://google.com
يكتب وثيقة هيكل {
الصفحات int
المراجع سلسلة
وقعت منطقي
}// اكتب يكتب مستندًا جديدًا إلى التخزين
//
// يمكنك التعرف على الكتابة من Wikipedia.com
funcيكتب() {
}
لاحظ أن Godoc يطلب منك كتابة عناوين URL كاملة لربطها. في هذا المثال ، يتضمن عنوان URL الخاص بـ Google ملف https: // البادئة ، لذلك يضيف Godoc رابطًا إليها. نظرًا لأن مجال Wikipedia ليس عنوان URL كاملًا من تلقاء نفسه ، فإن Godoc سيتركه بمفرده.
فيما يلي بعض أفضل المبادئ التي يجب تطبيقها عند توثيق كود Go الخاص بك:
- اجعل وثائقك بسيطة وموجزة.
- ابدأ جملة الدوال والأنواع والإعلانات المتغيرة بأسمائها.
- ابدأ سطرًا بمسافة بادئة لتنسيقه مسبقًا كرمز.
- التعليقات التي تبدأ بـ "BUG (الاسم)" مثل "BUG (joe): هذا لا يعمل" هي تعليقات خاصة. سوف يتعرف عليها Godoc على أنها أخطاء ويبلغ عنها في القسم الخاص بها من الوثائق.
يمكن أن يخفف Godoc من مشاكل التوثيق الخاصة بك
باستخدام Godoc ، يمكنك أن تكون أكثر إنتاجية ولا تقلق بشأن جهد توثيق برامجك يدويًا.
يجب أن تحافظ على وثائقك دقيقة ومفصلة وإلى الحد الذي يسهل على جمهورك المستهدف قراءتها وفهمها. من الضروري أيضًا أن تحافظ على تعليقات التعليمات البرمجية محدثة أثناء تعديل برنامجك.
تحقق من وثائق حزمة Godoc لمعرفة المزيد حول استخدام Godoc.