توثيق واجهات وتنفيذها [مغلقة]

Question

أنا أزين التعليمات البرمجية C# مع تعليقات لذا أنا يمكن أن تنتج ملفات تعليمات HTML.

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

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

يجب إنشاء/الوثيقة المخصصة الاستثناءات بحيث واجهات منفذي رمي هذه بدلا من تلك الإطار ؟

آمل أن يكون هذا هو واضح!

شكرا

تحرير يناير 4th 2010:قررت أن أكتب بلوق وظيفة حول هذا والعرف استثناءات .صافي في http://blog.mikecouturier.com/2010/01/creating-custom-exceptions-in-net-right.html

Answer 1

أنا لست متأكدا تماما فهمت سؤالك (و أنا جافا وليس C# المطور), ولكن يبدو أنك تسأل عن ما هو في الأساس مسألة تعدد الأشكال:إذا كان شخص ما يستخدم الأسلوب على واجهة التي أعلن لرمي X و Y, ماذا يحدث إذا كان تنفيذ رميات Z ؟

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

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

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

Answer 2

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

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

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