التوثيق على مستوى الطريقة في تطبيقات n-Tier

Question

حالتي:

تبدو سلسلة طلب البيانات الخاصة بطلبي كما يلي:

(Client) -> (WebService) -> (SQL or OLAP Cube)

العميل هو تطبيق Silverlight الذي يستخدم وكيلًا تم إنشاؤه للتواصل مع خدمة ويب WCF.والذي بدوره يقوم بالترخيص والوصول إلى SQL DB وOLAP Cubes باستخدام مكون DAL، في الأساس يقوم فقط بإعادة توجيه الطلبات.ولذلك فإن كل طريقة موجودة في أربعة أماكن مختلفة:

// WCF Webservice interface and implementation (used by client)
public interface ICatalogService 
public class CatalogService : ICatalogService

// DAL interface and implementation (used by webservice)
public interface ICatalogDataAccessLayer
public class CatalogDataAccessLayer : ICatalogDataAccessLayer    

الآن سؤالي، أين يجب أن أضع الوثائق لتحديد هذه الأساليب بوضوح؟على مستوى الفصل أو الواجهة، على DAL أو على خدمة الويب؟

أفكاري حتى الآن:

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

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

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

Answer 1

أعتقد أن معظم الناس يتوقعون أن يتم توثيق خدمة الويب بشكل أكثر كثافة من DAL (خاصة إذا كان DAL عبارة عن كود تم إنشاؤه في الغالب:أعتقد أن هذه طرق تمريرية).أود أن أضيف مؤشرًا إلى وثائق خدمة الويب في تعليقات DAL لأولئك الذين يعملون معها في المستقبل.

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

إذا تم تهديد DAL بإعادة الاستخدام من قبل عميل آخر بدون طبقة خدمة الويب...من الواضح أن هذا يغير الأمور لتتجه إلى الاتجاه المعاكس (أو لأتمتة التعليقات المكررة).