كيف ينبغي أن تكون التعليقات على طرق الواجهة والفئة مختلفة

Question

لقد واجهت هذه المعضلة عند العمل على تطبيق ويب ASP.NET باستخدام مصنع برامج عميل الويب (WCSF) في C#، ويمكن أن ينطبق الشيء نفسه على النظام الأساسي واللغات الأخرى. وضعي مثل هذا:

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

لذا فإن سؤالي هو: هل يجب أن يكون هناك اختلاف كبير بين محتوى الوثائق على طريقة الواجهة وطريقة الفئة المقابلة؟ هل يجب أن يركزوا على جانب مختلف أو شيء من هذا القبيل؟

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

Answer 1

أنا شخصياً أعتقد أن هذه التعليقات يجب أن تكون هي نفسها - يجب أن يقول كلاهما "ما ستفعله الطريقة" ، بشروطك.

لا يوجد سبب لتعليقات XML لذكر تفاصيل التنفيذ. الاستثناء الواحد ، من المحتمل ، هو ذكر الآثار الجانبية المحتملة (أي: قد تستغرق هذه الطريقة وقتًا طويلاً) ، لكنني شخصياً سأفعل ذلك في <remarks> قسم من التعليقات DOC XML.

Answer 2

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