Nunit: أفضل الممارسات لتعليقات مستند XML

يبدو جيدًا - كل ذلك لإعداد معيار. هناك قدر لا بأس به من xmldoc غير الصحيح والذي يمكن أن يفعله أيضًا مع الإصلاح. (معلمات خاطئة وما إلى ذلك)

أفترض أنك تخطط لقصر كل ما سبق على أنواع المواجهة العامة فقط؟

تضمين التغريدة

أفترض أنك تخطط لقصر كل ما سبق على أنواع المواجهة العامة فقط؟

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

سأصوت ضد إضافة المزيد إلى معايير الترميز لدينا. يجب أن تكون معايير البرمجة في حدها الأدنى وأن تتضمن فقط الأشياء التي نرغب في فرضها على الجميع. إذا كنا نحدد الفترات ، فأعتقد أننا نحصل على تفاصيل مفرطة.

غالبًا ما أخبر الفرق بالتفكير في معيار الترميز كما لو كان الرئيس - أي ، هل ترغب في ذلك إذا كان رئيسك يخبرك باستمرار بفعل هذا الشيء. في فريق مدفوع ذاتيًا ، يكون معيار الترميز ، بالطبع ، ليس رئيسًا. الفريق هو الرئيس و _ لا شيء _ يجب أن يكون في معيار الترميز ما لم يتفق معه الفريق بالفعل. لا تضع أشياء وتقول إنه يمكننا إجراء استثناء - فقط ضع أشياء لن تجعل أي استثناءات لها.

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

@ jnm2 لقد جعلت هذا ينطبق على الإطار فقط بحكم وضعه هنا. هل هذا هو نيتك؟

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

نعم ، أعتقد أن التلميع على أنواع المواجهة العامة لـ NUnit مهم بدرجة كافية لدرجة أنني سأطلب تغييرات على أي علاقات عامة لا تتضمن فترة ، كما كنت أفعل. هذا هو الحد الأدنى من المعيار الذي أعتبره شخصيًا مهمًا للاحتراف مثل طلب إصلاح خطأ مطبعي.

ونعم ، الإطار فقط. إطار العمل هو المكان الوحيد الذي يرى فيه المستخدمون وثائق XML ، أليس كذلك؟

@ jnm2 أعتقد أنني ربما قلت أولاً إنني أحب جميع نقاطك إذا كنت تتحدث عن دليل لكيفية كتابة تعليقات XML جيدة. لكنك قلت معيار الترميز ، وهو مجموعة من المتطلبات الإلزامية ، وهذا ما كنت أركز عليه.

@ jnm2 حسنًا ، ما

إليكم رأيي في ما يعنيه معيار الترميز ...

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

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

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

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

لكن هذا مجرد تصويتي. أنا مهتم بردة فعلك وبقية أعضاء الفريق على الفكرة. هل لديك رؤية لنوع من الأشرطة طويلة المدى التي سيتم تعيينها لجودة توثيق XML؟ كم سيكون ارتفاع الشريط؟ هل من الأفضل أن نبقى كما نحن بدون قيود طويلة الأمد؟

أعتقد أنني ربما قلت أولاً إنني أحب جميع نقاطك إذا كنت تتحدث عن دليل لكيفية كتابة تعليقات XML جيدة. لكنك قلت معيار الترميز ، وهو مجموعة من المتطلبات الإلزامية ، وهذا ما كنت أركز عليه.

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

@ jnm2

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

<chiding>
أنا آسف ، لكن يجب أن أتصل بك على هذا. إنها مغالطة أن تفترض أن أي شخص يختلف معك يجب ألا يشاركك قيم الصنعة الجيدة. هذه ، في الواقع ، هي النقطة الكاملة التي أحاول توضيحها بشأن المعايير. إذا كتب أحدهم معيارًا يقول "يجب أن تحتوي المستندات على كلمات مكتوبة بشكل صحيح" على سبيل المثال ، فإن المرء لا يذكر فقط ما هو واضح ولكنه يهين زملائه أعضاء الفريق. هذا هو بالضبط نوع المعيار الذي وجدته في العديد من الهيئات ، حيث أنشأت منظمة منفصلة سياسات وإجراءات للمبرمجين لاتباعها. مثلما لا نكتب معيارًا يقول "يجب كتابة برامج C # بشكل صحيح وتتبع مبادئ التنظيم الجيدة" ، لا نريد واحدًا يقول الشيء نفسه عن توثيق XML.

لا يتعلق خلافنا بالتوثيق أو قيمته أو الصنعة بشكل عام. يتعلق الأمر بطبيعة وهدف معيار الترميز.

إن الإيحاء بأن الشخص الذي يختلف معك يقدّر الصنعة الجيدة أقل مما تفعله هو حجة إعلانية من أسوأ أنواعها.
</chiding>

آسف على ذلك. 😄

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

ما تصفه (في رأيي) هو أشبه بـ "أفضل الممارسات في وثائق XML" بينما معيار الترميز (في تعريفي) أشبه بـ "الممارسات الدنيا". لا يهم إلا أنني أعتقد أننا في الواقع بحاجة إلى شيء يصف الحد الأدنى في كثير من الأحيان.

على سبيل المثال ، الكثير مما يتم القيام به على NUnit يقوم به المساهمون العاديون. الآن ، إذا أرسلنا الأشخاص بعيدًا عندما لم يتبعوا جميع أفضل ممارساتك ، فقد لا يعودون وسيكون لدينا عدد أقل من المساهمين. OTOH ، إذا قبلنا عملهم ثم عملنا على تحسينه بالإضافة إلى جعلهم يقومون بعمل أفضل في المرة القادمة سيكون لدينا فرصة أفضل للاحتفاظ بهم.

أخيرًا ، يجب أن أضيف هذا: __إذا كانت أفكارك جيدة جدًا ، فلماذا تحتاج إلى قوة السلطة "القانونية" وراءها؟ 😸 أنا شخصياً لا أعتقد أنك تفعل ذلك.

أعلى معاييرنا هي أننا لن ندمج أي شيء ما لم يوافق عليه اثنان من الملتزمين. كل شيء آخر هو تعليم ، وليس تطبيقًا.

إنها مغالطة أن تفترض أن أي شخص يختلف معك يجب ألا يشاركك قيم الصنعة الجيدة.

أنا آسف! ليس المعنى الذي قصدته على الإطلاق. وأنا أتفق مع ما تقوله.

هذا ما أحاول تعلمه. إذا انتهينا جميعًا إلى الاتفاق على أننا نريد أن نكون في مكان يكون فيه لكل جملة توثيق XML علامة نهاية لأننا نعتقد أن هذه تجربة أفضل للمستهلك ، فعلينا أن نختار كيف نصل إلى هذا المكان:

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

لذا إذا سألت بشكل أكثر وضوحًا ، ما الذي أتغاضى عنه؟

الآن ، إذا أرسلنا الأشخاص بعيدًا عندما لم يتبعوا جميع أفضل ممارساتك ، فقد لا يعودون وسيكون لدينا عدد أقل من المساهمين.

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

ربما يكون هناك فجوة بين كيفية استخدام معايير الترميز لدينا حاليًا ، وما نريدها أن تكون. لقد حصلت للتو على نقرة سريعة الآن - هناك أجزاء وأجزاء هناك لم أكن أعرف عنها ، ولم أكن لأفرضها في المراجعة ، أو حتى مكتوبة في الكود الخاص بي! 😄

افكاري:

• وثيقة لتقديم إرشادات تنسيق xmldoc تبدو جيدة - بالضبط ما نسميه هذا المستند ، لست قلقًا للغاية!
  
  
  
  • سأكون حذرًا أيضًا من إعادة الأشخاص لمجرد تصحيح بضع نقاط توقف كاملة في العلاقات العامة. ومع ذلك ، فإن المشاريع الأخرى تعمل على هذا النحو (الكيك) - ويبدو أنها تعمل بشكل جيد بما فيه الكفاية بالنسبة لهم.
  
  
  • آمل أيضًا أنه بمجرد أن يصبح xmldoc الحالي أكثر توحيدًا ، سيتمكن الأشخاص من التقاط الاتفاقية ، وقد لا يكون ما سبق مشكلة شائعة.
  
  

سأكون حذرًا أيضًا من إعادة الأشخاص لمجرد تصحيح بضع نقاط توقف كاملة في العلاقات العامة.

إذا رآها المساهم في نفس ضوء الخطأ المطبعي ، عبر الإرشادات أو من خلال رؤية ما تفعله الملفات القريبة ، فمن المحتمل أن يكونوا متحمسين لإصلاحها. هذا يعتمد ، هل هذه هي الطريقة التي نريد أن نراها ونقدمها؟

أتفق معCharliePoole. اقل هو الافضل!

أنا في الواقع لا أحب شرط الفترة. أعتقد أنه يفسد الأمور. لم أستخدم النقاط في تعليقات xml الخاصة بي. لم يشتك أحد من أي مشروع شاركت فيه.

شكرًا على هذه التعليقات ،oznetmaster.

نستطيع:

• لا تفعل شيئًا (قد أطلب علامات النهاية على الجمل ... 😈)
• قرر أنه من الجيد أن تمتلك NUnit أنماطًا مختلطة في وثائق XML الخاصة بها (أتوقف عن طلب مثل هذه التغييرات)
• قرر أننا نريد نمطًا أو آخرًا

@ jnm2 بدءا من جديد! أنا __فقط _ لا أوافق على __ كلمتين__ في اقتراحك الأصلي: "معيار التشفير". أتفق في الواقع مع معظم الأشياء الأخرى - أتجنب تشويش هذه المناقشة بالتفاصيل في الوقت الحالي.

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

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

يقول معظم الخبراء الذين أحترمهم أنك __لا_ تضع أفضل الممارسات في معيار الترميز. أنت تسمح للفريق بتطوير أفضل ممارساته. في كثير من الأحيان ، هناك العديد من الممارسات "الأفضل" (أو الجيدة) وليس من الضروري في الواقع الاختيار بينها مرة واحدة وإلى الأبد. يطلق عليه "الثقة في الناس في السياسات والإجراءات".

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

لكن كما قلت ، لا أعتقد أننا بعيدون جدًا ولكننا نركز فقط على أشياء مختلفة. عندما تقول معيار التشفير ، أسمع شيئًا يجب اتباعه تمامًا - لا يوجد حكم. أريد أن يكون الحد الأدنى لأنني __أريد_ أن يستخدم الناس الحكم. إذا كانت لدينا مجموعة من أفضل الممارسات أو الموصى بها ، فسيستخدم معظم الناس حكمهم من خلال اتباعها. في النهاية ، هؤلاء الأشخاص الذين يقضون معظم الوقت في الكود "سيفوزون" بجعل الأشياء بالطريقة التي يعتقدون أنها يجب أن تكون - وهذا هو ما ينبغي أن يكون في المصدر المفتوح.

عادةً ما يكون عنصر تعليق xml عبارة عن "جملة" واحدة.

إذا لم يكن الأمر كذلك ، فعادة ما أستخدم عنصر الفقرة لكل "جملة".

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

أعتقد أنه حتى محاولة كتابة "أفضل الممارسات" لوثائق xml قد يكون منحدرًا زلقًا.

على الفور ، فإنه يثير أسئلة مثل "ما هي اللغة الإنجليزية التي نتحقق منها إملائيًا"؟ ما الثقافة التي نستخدمها للأعداد وفواصل القوائم؟ مسافة واحدة أو اثنتين بعد فترة (إذا سمحنا / طلبنا فترات).

أعتقد حقًا أن هذا بعيد قليلاً عن المكان الذي يجب أن نركز فيه انتباهنا!

هل يوجد / أو معيار ترميز أو أفضل الممارسات لصفحات التوثيق؟

CharliePoole حسنًا ، أعتقد أننا على نفس الصفحة الآن.

oznetmaster أعتقد أن هذه الأسئلة خارج نطاق توثيق XML ، على الأقل في الوقت الحالي. وإذا توصل فريق إطار عمل NUnit بطريقة ما إلى إجماع على أن هناك حاجة إلى تنسيق القوائم بطريقة معينة ، فلماذا يكون هذا أمرًا سيئًا؟ الأمر متروك حقًا للفريق؟

لا أرى لماذا هم خارج النطاق. فهي ذات صلة مثل علامات الترقيم للجملة.

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

أعتقد أن فرضيتك بأكملها هي أن وثائق xml للجانب المواجه للجمهور من إطار العمل يجب أن تكون متسقة لأنها الطريقة التي يرى بها مستخدمو NUnit في أغلب الأحيان NUnit. هذا جزء من الاتساق.

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

أعتقد أنه يمكننا إجراء محادثة حول ما إذا كنا نريد أفضل ممارسة حول علامات النهاية دون إجراء أي محادثة أخرى ممكنة.

@ jnm2 أعتقد أن هذا قصير النظر إلى حد ما. "أفضل الممارسات" فقط لعلامات النهاية؟

أسأل مرة أخرى. هل هناك "أفضل الممارسات" المكافئة لصفحات التوثيق؟ إذا لم يكن الأمر كذلك ، فسأعتقد بالتأكيد أنه سيكون أولوية أعلى بكثير إذا كان الاتساق هو ما يتم السعي إليه هنا.

على سبيل المثال ، عملت لدى شركة واحدة حيث كانت جميع تعليقات xml بأحرف صغيرة. لا يوجد قبعات في بداية السطر. ربما نحتاج إلى دراسة قضايا البداية والنهاية؟

تقدم Microsoft هذه التوصيات: https://docs.microsoft.com/en-us/dotnet/csharp/codedoc .

خاصة:

Documenting code is recommended for many reasons. What follows are some best practices, general use case scenarios, and things that you should know when using XML documentation tags in your C# code.

-     For the sake of consistency, all publicly visible types and their members should be documented. If you must do it, do it all.
-     Private members can also be documented using XML comments. However, this exposes the inner (potentially confidential) workings of your library.
-     At a bare minimum, types and their members should have a <summary> tag because its content is needed for IntelliSense.
-     Documentation text should be written using complete sentences ending with full stops.
-     Partial classes are fully supported, and documentation information will be concatenated into a single entry for that type.
-     The compiler verifies the syntax of the <exception>, <include>, <param>, <see>, <seealso> and <typeparam> tags.
-     The compiler validates the parameters that contain file paths and references to other parts of the code.
- 

يسعدني أن أوافق على التوصية بهذه باعتبارها أفضل الممارسات لوثائق NUnit XML ، ولا أقضي المزيد من الوقت في هذه المسألة.

@ nunit / framework-team حسنًا ، إليك الإرشادات السبعة التي أود مناقشتها:
https://gist.github.com/jnm2/3f230c9f6343d60bb542938dc35e7a96

س 1: أي من هذه الأشياء التي ترغب في اعتبارها أفضل الممارسات التي تؤثر على منتج NUnit Framework؟

س 2: إلى جانب جعل مستند أفضل الممارسات قابلاً للاكتشاف ، هل نرغب في طلب التغييرات إذا لاحظنا أن أحد الممثلين العامين لا يتبع هذه الإرشادات؟ إذا لم يكن الأمر كذلك ، فهل نريد تحسين توثيق XML العام لاحقًا؟

نرحب بالتعديلات.

يجب ألا تؤثر أفضل الممارسات أبدًا على العلاقات العامة أو قبولها!

كما أشرت أعلاه ، أفضل اعتماد "أفضل الممارسات" المتداولة على نطاق واسع والمستخدمة على نطاق واسع ، كما هو موثق من قبل Microsoft في الرابط أعلاه.

@ jnm2

فقرة المقدمة: اذكر نطاق هذا. أود تطبيقه على تجميعات framework و engine.api ، والتي تتطلب xml doc في جميع الطرق العامة لتجنب أخطاء المترجم.

عن سؤالك الأول ...

تمرين 1: طلب ترقيم نهاية (وليس نقاط) لجميع الجمل. لغير الجمل ، لا تستخدم.

تدريب 2: سأستخدمها باعتدال. لا نحتاج إلى مرجع لسلسلة أو int على سبيل المثال.

الممارسة 3: سأضيف الجمهور. حيث تقول أنه من المقبول إزالة الإضافة: إلا في التجميعات حيث يتسبب ذلك في حدوث خطأ في المترجم.

ممارسة 4: ما لم يكن واضحًا. على وجه الخصوص ، لا تستخدم على الخصائص.

الممارسة الخامسة: نعم

الممارسة السادسة: نعم

تمرين 7: كن مقتصدًا. لا تسرد الاستثناءات التي قد يتم طرحها بواسطة أي أو معظم استدعاءات الطريقة. لا يعجبني مثالك هنا لأنه (1) يسرد المعلومات مرتين و (2) يستخدم cref لاستثناء .NET مدمج يعرفه الجميع بالفعل. سأقوم فقط بتخليص الأشياء الخاصة بنا ، على كل حال.

لسؤالك الثاني ...

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

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

oznetmaster تتضمن إرشادات Microsoft سبع نقاط. تعليقاتي...

1. "من أجل الاتساق ..." هذا ليس سبب توثيقنا. نحن نوثق حتى يعرف الناس كيفية استخدام برامجنا. الجملة الثانية في هذه النقطة لا معنى لها بالنسبة لي.

2 ، 3 ، 4. يكون لها معنى كمبادئ توجيهية.

5 ، 6 ، 7. هي بيانات حول المترجم ، وليست إرشادات للتوثيق.

مجرد أخذ 2 و 3 و 4 يجعلني دليلاً مقبولاً بالنسبة لي.

بصراحة ، لا أشعر بالحاجة إلى مثل هذا المبدأ التوجيهي ، ولكن بما أن @ jnm2 يفعل ذلك وهو مستعد للعمل عليه ، أعتقد أنه يجب أن يشعر بالحرية في القيام بذلك.

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

CharliePoole يعمل لي.

يبدو هذا جيدًا بالنسبة لي ، مع قصره على الأنواع العامة فقط.

سيكون الاتساق أمرًا رائعًا ، لكنه قاعدة بيانات قديمة جدًا ولدينا وقت محدود يُنفق بشكل أفضل في إصلاح الأخطاء وإضافة الوظائف. ومع ذلك ، أعتقد أننا يجب أن نبحث عن وثائق مضللة وأعتقد أيضًا أننا يجب أن نضيف معلومات إضافية مثل <see cref="xxx"/> كلما أمكن ذلك لتحسين تجربة الأدوات.

أيضًا ، من الواضح أنه Colour وليس Color 😝

ChrisMaddock أيهما يبدو جيدًا بالنسبة لك ، سواء Microsoft أم @ jnm2 ؟ أعتقد حقًا أننا يجب أن نختار الثلاثة الذين أشار

oznetmaster - عذرًا ، لم أدرك أننا كنا نبحث في كلا الخيارين.

ليس لدي أي اعتراض على الخيار الأكثر تحديدًا @ jnm2 المقترح. يبدو أن مستخرج Microsoft هو مجموعة فرعية من ذلك.

هذا ليس شيئًا لدي اهتمامًا كبيرًا بالهجوم - ولكن إذا أراد @ jnm2 رفع قاعدة الشفرة الحالية إلى هذا المعيار ، فسيكون ذلك بلا شك تحسنًا. هذا جزء من كونه مشروعًا مفتوح المصدر غير احترافي في نظري ، فسيكون مدفوعًا دائمًا إلى حد ما بما يهتم الفريق بالعمل عليه.

أنا جميعًا لكتابة مستند "توجيهي" ، والعمل على تحقيق ذلك في معظم الأحيان - سأكون سعيدًا بمتابعته في العلاقات العامة الخاصة بي. أنا أقل حرصًا على فكرة إعادة المساهمين العرضيين لإجراء تغييرات طفيفة في الأسلوب - لكنني أعتقد أننا تطرقنا إلى ذلك من قبل ، ويجب التعامل مع ذلك على أساس كل حالة على حدة.

أنا أيضًا يمكن أن أعيش مع أي منهما ، دائمًا ما يكون هادئًا مع القليل من البراغماتية.

مراجعة كود WRT ، هذا مجال أود أن أرى فيه التغييرات المقترحة أو الموصى بها ، مع وجود تبرير يساعد الأشخاص على فهم المستند بدلاً من مجرد الإشارة إليه. في حالة معايير الترميز ، نشير فقط إلى المستند ونقول "فقط أضف الشرطات السفلية كما هو موضح." هنا ، OTOH ، نريد أن نقول ، "سيساعد المستخدمين إذا قمت بذلك ..."

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

لقد قمت بدمج التعليقات في هذه الصفحة: https://github.com/nunit/docs/wiki/Best-practices-for-XML-documentation.

تضمين التغريدة

يستخدم cref لاستثناء .NET مدمج يعرفه الجميع بالفعل. سأقوم فقط بتخليص الأشياء الخاصة بنا ، على كل حال.

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

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