التعليق الرمز: هل وضعت تعليقات التعليمات البرمجية الخاصة بك على واجهات أو على فصول ملموسة، أو كليهما؟ [مكرر

https://stackoverflow.com/questions/1875440

18-09-2019
|

سؤال

هذا السؤال لديه بالفعل إجابة هنا:

التعليق على الواجهة، التنفيذ أو كليهما؟ 8 إجابات

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

فيما يلي مثال حيث يتم تكرار التعليقات:

public class Foo : IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    public void DoSomething()
    {
    }
}

public interface IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    void DoSomething();
}

المحلول

أود أن أضع تعليقات على حد سواء.

على واجهات، أود التعليق على النية وراء أعضاء الواجهة واستخدامها.

في التنفيذ، سأعلق على أسباب التنفيذ المحدد.

نصائح أخرى

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

أضعها في كليهما، لكن الألم الذي يحفظه في المزامنة، عندما تكون في شك أنا فقط أضعها على الواجهة.

أقوم بذلك لأنني أحب Tooltip عند استخدام التعليمات البرمجية، والتي يجب أن تستخدم دائما الواجهة ...

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

كلاهما، لكنني أتمنى أن يكون هناك وظيفة في الوظيفة لإبقائها في المزامنة

علامة <referTo>System. .... </referTo> لربط التعليقات ستكون مثالية

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

فقط للواجهات. لأنه في هذه الحالة لا أحتاج إلى مزامنة لهم. يساعدني IDE في رؤية تعليقات واجهة في فصول ملموسة. و API مولد المستندات يفعل نفسه.

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

مرخصة بموجب: CC-BY-SA مع الإسناد

لا تنتمي إلى StackOverflow