كيفية توثيق طريقة تمديد صحيح

Question

وهكذا، لدي بعض طرق الإرشاد، عن الاشياء التي يشيع استخدامها، وتوثيقها، وانها وقعت لي أن لدي <م> أي فكرة كيفية باستمرار كتابة الكود summary في التعليقات XML. على سبيل المثال:

    /// <summary>
    ///     Gets a subset of characters from the left-hand side of a string.
    /// </summary>
    public static string Left(this string value, int length)

ومقابل.

    /// <summary>
    ///     Gets the name of the month for this date.
    /// </summary>
    public static string MonthName(this DateTime value)

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

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

Answer 1

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

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

وشيء آخر ... في بعض الأحيان قد تجد نفسك (مثل HtmlHelper في MVC) حيث كنت توسيع كائن من الاتفاقية بدلا من ضرورة. وهذا يعني أنه لا يهم إذا كان الكائن الذي يتم تمديدها باطل أم لا لأن أسلوب لا يعمل عليه. في حين أن اتفاقية (أعتقد) هي رمي عند الكائن this باطل، لكنني أفضل للسماح للطريقة كاملة بشكل طبيعي وثيقة هذه الحقيقة في مساعدة (أي، "... وهذا يمكن أن يكون لاغيا" أو "... لاغية قيمة صالحة لهذه الوسيطة. ")