ما هي فضائل استخدام تعليقات XML في .NET؟

Question

لا أستطيع أن أفهم فضائل استخدام تعليقات XML. أعلم أنه يمكن تحويله إلى وثائق لطيفة خارجية إلى الكود ، ولكن يمكن تحقيق الشيء نفسه مع بناء جملة Doxygen الأكثر موجزة. في رأيي ، فإن تعليقات XML خاطئة ، لأنه:

1. إنهم يعشقون التعليقات والرمز بشكل عام. (يصعب قراءتها من قبل البشر).
2. يمكن عرض كود أقل على شاشة واحدة ، لأن "الملخص" و "/ملخص" يأخذون خطوطًا إضافية.
3. (إزالة)

ما الذي كان يمكن أن يكون بعد ذلك هو الأسباب ، لماذا تم تفضيل XML في .NET بدلاً من ذلك بناء جملة doxygen البسيطة؟

Answer 1

لا يوجد حقًا إجابة صحيحة هنا IMO. لا يوجد نظام "أفضل" من الآخر في الواقع - كلاهما يقوم بنفس الوظيفة في النهاية ، وهو ما يسمح لك بإنشاء وثائق التعليمات البرمجية.

يمكن تنسيق الناتج النهائي بنفس الطريقة تمامًا لكل منهم ، ولديهم نفس الوظائف إلى حد كبير من حيث التسميات وما إلى ذلك ، وبالتالي فإنها تصل حقًا إلى الخيار الشخصي هنا.

أنا شخصياً أجد أن تعليقات XML أكثر قابلية للقراءة إنسانية ، وأكثر منطقية وسهلة الاستخدام - ولكن مع ميزة إضافية تتمثل في إنشاء Visual Studio تلقائيًا ، انهيارهم حتى لا يشغلوا مساحة كبيرة على الشاشة. أنا متأكد من أن شخصًا يأتي من تحرير الخلفية في السادس أو بعضها سيكون له رأي مختلف ، ولكن لا توجد ميزة حقيقية لأي منهما.

لذلك أود أن أقول إن هذا الأمر يعتمد حقًا على ما تستخدمه وما تستخدمه أنت وفريقك في استخدامه.

الآن إذا كنت تسأل لماذا اختارت Microsoft الاندماج بإحكام مع التعليق XML داخل Visual Studio ، فهذا سؤال مختلف. على الأرجح ، يرجع ذلك إلى الحقائق التي: سيكون من الأسهل بالنسبة لهم تنفيذها ضمن VS (حيث يمكنهم إعادة استخدام التعليمات البرمجية الحالية لإنشاء/قراءة التعليقات وبناء Intellisense وما إلى ذلك) ، لديهم اتجاه للالتزام بـ "المعايير" "على أي حال (سواء كان ذلك الخاص بهم أو الصناعة) ، وكذلك أسباب الترخيص كما ذكر جيف.

فقط لإضافة أن المنتج Microsoft تستخدمه داخل VS يسمى "Sandcastle" ، وهي أداة توليد DOC في المنزل. لديها صفحة wiki الخاصة بها @ http://docproject.codeplex.com/wikipage

Answer 2

1. تلتقط IDE التعليقات ويظهرها عند استخدام هذه الطريقة.
2. من المحتمل أن يكون كل من برامج C# على دراية بنظام التعليق XML. هناك أقل للتعلم لتوظيف جديد.

أنا لا أقول أن Doxygen ليس أفضل ، إنه مجرد نظام التعليق XML أكثر دراية بالجميع ، وهذا يقطع شوطًا طويلاً. إنه مجرد شيء واحد أقل عليك تدريبه على توظيف جديد للقيام به.

بقدر ترك المتغيرات غير معقولة. ما قد يكون واضحًا لك ، لن يكون لشخص آخر (أو لك بعد 6 أشهر).

حسنًا ، أعتقد الآن أنني أرى ما تطلبه.

1. التعليقات المحطمة. يساعد ترميز اللون. شخصياً ، أقوم بمسح النص الرمادي بسرعة وأقرأ فقط ما هو أخضر ما لم أكن بحاجة إلى قراءة نص XML. (في إعداداتي على الأقل).

2. لدينا شاشات كبيرة حتى نحصل على المزيد من التعليمات البرمجية على الشاشة بشكل عام. (من أرخص شراء شاشة كبيرة من إعادة تدريب الناس بشكل عام). الشيء الآخر في هذا الأمر أيضًا ، هو أنني أراهن أنك تبحث بنشاط في وظيفة واحدة فقط في وقت واحد ، لذلك إذا كانت هذه الوظيفة بأكملها تتناسب مع صفحة ، فربما لا تعاني من عدم رؤية المزيد من التعليمات البرمجية. الآن إذا كانت الوظائف طويلة ، فقد أرى أن هذه مشكلة.

3. نضع التعليقات الموجزة على سطر واحد عندما يكون ذلك ممكنًا (على افتراض أنه ليس كبيرًا حقًا). هذا يقلل من المساحة المستخدمة.

4. لا أعرف ما إذا كان Doxygen يقوم بذلك ، ولكن يمكنك انهيار التعليقات حتى تكون خارج الطريق.

Answer 3

الوظيفة الأساسية لوثائق XML هي ليس لتوليد الوثائق. إنه لتوفير معلومات جيدة عن عميل صفك. شحن ملف .xml الذي تم إنشاؤه مع التجميع الخاص بك.

Answer 4

فضائل استخدام تعليقات XML في .NET

يتم دعمها أصليًا من قبل برنامج التحويل البرمجي C# و Visual Studio ، حيث يوفر موقعًا واحدًا لتوثيق واجهة برمجة التطبيقات الخاصة بك للاستخدام في وثائق مطبوعة وعبر الإنترنت وبين Intellisense.

هذا المقال من مجلة MSDN ينص على ما يلي:

في كل مشروع ، هناك شخص غير سعيد بالوثائق. يريد الفريق المزيد من التعليقات في المصدر ، ويريد الكتاب الفنيون المزيد من المعلومات المكتوبة حول تصميم التعليمات البرمجية ، وضمان الجودة يريد رؤية المواصفات الوظيفية ، وما إلى ذلك. إذا كانت كل هذه الوثائق مكتوبة بالفعل ، فلا يزال لديك معركة إبقائها جميعها متزامنة.

على الرغم من أن التنسيق ليس مثاليًا بالضرورة ، فإن تعليقات وثائق XML توفر بناء جملة غنية بحيث يمكن تحقيق ذلك.

لماذا لا تدعم doxygen في C# بدلاً من ذلك؟

أما بالنسبة لسبب اختيار نظام XML الحالي على Doxygen ، فإنني أشك في أن هذا يرجع إلى ذلك في المقام الأول Doxygen تم إصداره تحت GPL مما يعني أن Visual Studio ومترجم C# سيحتاج أيضًا إلى إصداره على هذا النحو - وهو أمر لا ترغب Microsoft بلا شك في القيام به شروط GPL.

Answer 5

ما أجده أكثر تفكيرًا هو شعبية Ghostdoc توصيل في. إذا تمكنت تلقائيًا من إنشاء تعليق بناءً على اسم الطريقة ، فلماذا يكون التعليق على الإطلاق؟

يقول ستيف إيغج ذلك على التعليق هي علامة مبرمج مبتدئ ، لدي صعوبة في الاختلاف معه.

Answer 6

لم تكن لديك لاستخدامها في مشاريعك.

هم انهم أ المعيار الذي يتم دمجه في Visual Studio ، وإذا كنت تستخدم StyleCop ، فيمكن تطبيقها. لذلك هذه هي الفضيلة هنا.

ومع ذلك ، إذا قررت أنك تريد استخدام Doxygen ، فلا يوجد شيء يمنعك. فقط تأكد من أنك متسق.