ما هي أفضل الممارسات لتوثيق رمز C# مع تعليقات XML؟

Question

سأمر ببعض التعليمات البرمجية الجديدة التي كتبتها للتو وأضيفت تعليقات Sytle NDOC إلى فصولي وأساليب. آمل أن أقوم بإنشاء وثيقة جيدة نمط MSDN للرجوع إليها.

بشكل عام ، ما هي بعض الإرشادات الجيدة عند كتابة التعليقات لفصل ولأسلوب ما؟ ماذا يجب أن تقول تعليقات NDOC؟ ماذا لا ينبغي أن يقولوا؟

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

Answer 1

في التعليقات المستخدمة لبناء وثائق API ، يجب عليك:

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

• قائمة جميع الشروط المسبقة للمعلمات الخاصة بك (لا يمكن أن تكون فارغة ، يجب أن تكون ضمن نطاق معين ، وما إلى ذلك)

• سرد أي عوامل مادية يمكن أن تؤثر على كيفية تعامل المتصلين مع قيم الإرجاع.

• سرد أي استثناءات قد يرميها الطريقة (وتحت أي ظروف).

• في حالة وجود طرق مماثلة ، اشرح الاختلافات بينهما.

• لفت الانتباه إلى أي شيء غير متوقع (مثل تعديل الحالة العالمية).

• تعداد أي آثار جانبية ، إذا كان هناك أي.

Answer 2

إذا انتهى بك الأمر بالتعليقات التي لا تضيف أي قيمة ، فهي تضيع فقط.

فمثلا

/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)

... لقد أضفت أي قيمة على الإطلاق وأضفت المزيد من التعليمات البرمجية للحفاظ عليها.

في كثير من الأحيان ، يتناثر الكود مع هذه التعليقات الزائدة.

Answer 3

Stylecop يوفر تلميحات للرمز و أسلوب التعليق. الاقتراحات التي يقدمها تتماشى مع نمط توثيق MSDN.

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

Answer 4

بالنسبة للممتلكات ، يجب أن يشير تعليقك إلى ما إذا كانت العقار قد تم قراءة فقط أو اكتب فقط أو قراءة الكتابة. إذا نظرت إلى جميع وثائق MS الرسمية ، تبدأ تعليقات Doc Property دائمًا بـ "Gets ..." ، "Get أو Sets ..." و (نادرًا جدًا ، تجنب كتابة خصائص فقط) "مجموعات ..."

Answer 5

لا تنسى ما هو XML صالح. فمثلا:

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

(خطأ: XML غير صالح).

Answer 6

أنا أكتبu003Csummary> التعليق لتضمين المعلومات التي أرغب في معرفة ما إذا كنت أنا الذي يدعو تلك الوظيفة (أو إنشاء إنشاء تلك الفئة).

أنا أكتبu003Cremarks> التعليق لتضمين المعلومات التي أرغب في معرفة ما إذا كنت مكلفًا بتصحيح الأخطاء أو تعزيز هذه الوظيفة أو الفصل. ملاحظة: هذا لا يحل محل الحاجة إلى تعليقات جيدة. ولكن في بعض الأحيان تكون نظرة عامة عامة على الأعمال الداخلية للوظيفة/الفئة مفيدة للغاية.

Answer 7

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

جمع مع /doc وسيقوم برنامج التحويل البرمجي بالبحث عن جميع علامات XML في الكود المصدري وإنشاء ملف وثائق XML ، ثم استخدم أداة مثل Sandcastle لتوليد المستندات الكاملة.

Answer 8

شيء واحد في التعليقات هو تحديثها. الكثير من الناس يغيرون وظيفة ثم لا تغير التعليق ليعكس التغيير.