في أي بيئة مهنية ، يعد التوثيق الصحيح للكود الخاص بك مع التعليقات ضروريًا لسهولة القراءة على المدى الطويل. بالنسبة إلى رمز. NET ، توفر Microsoft نظامًا للتعليقات المستندة إلى XML والتي توفر دعم IDE محسّنًا.
ما هي تعليقات XML؟
بشكل أساسي ، تعليقات XML هي نوع خاص من التعليقات يُشار إليها بشرطة مائلة ثلاثية (
///) وعلامات XML لإعطاء التعليق بعض البنية. على سبيل المثال ، قد يبدو التعليق الموجز البسيط كما يلي:
الهدف من ذلك هو أنه عندما تذهب لاستخدام هذه الطريقة في مكان آخر في التعليمات البرمجية الخاصة بك ، يمكن لبرنامج Visual Studio إلقاء نظرة على XML وإضافة بعض المعلومات مباشرةً في نافذة Intellisense المنبثقة. يعمل هذا النظام مع جميع أنواع الأنواع ، ويمكن استخدامه حتى لتوثيق قيم الإرجاع والمعلمات الفردية. وعندما تقوم بتوزيع التجميع ، يمكنك توزيع ملف XML معه لتمكين هذه الميزات نفسها لأي شخص يستخدم مكتبة الفصل الدراسي الخاصة بك. يتيح ذلك أيضًا سهولة استخدام مولدات التوثيق الثابتة مثل DocFX و Sandcastle.
من المستغرب أن هذه الميزة هي في الغالب مجرد شيء. NET. لا شيء يمنعك من استخدام هذه الممارسة مع لغات أخرى ، ولكن هذا شيء تدعمه Microsoft جيدًا للغاتها ومحرريها ، وعادةً لا تحظى اللغات الأخرى بدعم مناسب لها. نود أن نرى دعمًا موسعًا لهذا النطاق ليشمل لغات ومحررين آخرين ، لأنه مفيد جدًا على مستوى العالم.
إنه سهل الاستخدام للغاية.اضغط ببساطة على المفتاح المائل ثلاث مرات (
///) فوق طريقة أو فئة أو أي نوع آخر ، وسيقوم Visual Studio بإدراج قالب لك للكتابة فيه. وهذا يوفر عليك المتاعب من كتابتها يدويًا ، مما يعني أنه لا يوجد سبب حقيقي لعدم استخدام هذه التعليقات على التعليقات المزدوجة المائلة التقليدية.
إذا كانت طريقتك تحتوي على نوع إرجاع أو معلمات ، فسيقوم Visual Studio بإنشاء حقول لها أيضًا. سترى تعليقاتك عندما تذهب لاستخدام الطريقة:
يدعم المعيار العديد من أنواع العلامات:
- يظهر في Intellisense كلما استخدمت الطريقة
- يشبه الملخص ، لكنه لا يظهر في Intellisense (مفيد لكتابة الوثائق الموسعة).
- يوثق نوع الإرجاع.
- يتيح للمطورين معرفة الاستثناءات التي يمكن للطريقة طرحها.
- يشبه المرتجعات لكن لخصائص الفئة.
- يظهر مثال رمز للوثائق (استخدم هذا مع).
- وإنشاء روابط قابلة للنقر لطرق أخرى ، تُستخدم عادةً لتوثيق الأحمال الزائدة.
- يسمح باستخدام القوائم لترتيب العناصر.
يمكنك قراءة وثائق Microsoft حول معيار تعليق XML لمزيد من المعلومات.
