इंटरफ़ेस, कार्यान्वयन या दोनों पर टिप्पणी करें?

Question

मुझे लगता है कि हम सभी (जब हम परेशान हो सकते हैं!) हमारे इंटरफेस पर टिप्पणी करते हैं। जैसे

/// <summary>
/// Foo Interface
/// </summary>
public interface Foo
{
    /// <summary>
    /// Will 'bar'
    /// </summary>
    /// <param name="wibble">Wibble factor</param>
    void Bar(string wibble);
}

क्या आप कार्यान्वयन पर टिप्पणी करते हैं (जो ग्राहकों को भी प्रदान किया जा सकता है, उदाहरण के लिए एक पुस्तकालय के भाग के रूप में)? यदि हां, तो आप दोनों को सिंक में रखने का प्रबंधन कैसे करते हैं? या क्या आप केवल 'प्रलेखन के लिए इंटरफ़ेस देखें' टिप्पणी जोड़ते हैं?

धन्यवाद

Comments

यहाँ के माध्यम से एक डुप्लीकेट

— घोंघा

Answer 1

एक सामान्य नियम के रूप में, मैं कोड के साथ ही DRY (रिपीट योरसेल्फ) सिद्धांत का उपयोग करता हूं:

• इंटरफ़ेस पर, इंटरफ़ेस का दस्तावेज़
• कार्यान्वयन पर, कार्यान्वयन की बारीकियों का दस्तावेजीकरण करें

जावा विशिष्ट : कार्यान्वयन का दस्तावेजीकरण करते समय, इंटरफ़ेस से "@" javadocs को "@inheritDoc" टैग का उपयोग करें।

अधिक जानकारी के लिए:

• आधिकारिक javadoc प्रलेखन
• कुछ अनौपचारिक सलाह ।

Comments

@InheritDoc टैग

— पॉल

वाह ... मुझे पता नहीं था {@inheritDoc} या तो अस्तित्व में है! मैं इसे आज से नियमित रूप से उपयोग करूँगा।

— शुक्राणु

C # के लिए, आप उपयोग कर सकते हैं <inheritdoc />, जो SandCastle द्वारा समर्थित है। ( अधिक जानकारी ... )

— डैनियल एए पल्सेमेकर

विरासत में मिली श्रेणी के भीतर गुण और अन्य तत्व केवल इंटरफ़ेस पर निर्दिष्ट होने पर टूलटिप में एक्सएमएल प्रलेखन नहीं दिखाते हैं। एक ही वर्ग के बाहरी उपयोग के लिए, यह दिखाई देता है। यह Visual Studio 2015

— SondreB

यहाँ लिंक @Virtlink सैंडकैसल / SHFB के लिए प्रदान की एक अद्यतन संस्करण है inheritdoc: पेज ewsoftware.github.io/XMLCommentsGuide/html/...

— बांध

Answer 2

यदि आप घोस्टडॉक एडिन का उपयोग करते हैं , तो यह इंटरफ़ेस से टिप्पणी के साथ कार्यान्वयन को अपडेट करता है जब आप राइट क्लिक करते हैं और विधि पर "दस्तावेज़ यह" चुनें।

Answer 3

C # के लिए यह IMO पर निर्भर करता है: यदि आप स्पष्ट इंटरफ़ेस कार्यान्वयन का उपयोग करते हैं, तो मैं कार्यान्वयन का दस्तावेजीकरण नहीं करूंगा।

हालाँकि यदि आप इंटरफ़ेस को सीधे लागू करते हैं और अपनी वस्तु के साथ इंटरफ़ेस के सदस्यों को उजागर करते हैं तो इन विधियों को भी प्रलेखित किया जाना चाहिए।

जैसा कि नाथ ने कहा, आप एक इंटरफ़ेस के प्रलेखन को क्रियान्वयन में डालने के लिए घोस्टडॉक का उपयोग कर सकते हैं। मैंने इस कमांड को Ctrl + Shift + D शॉर्टकट के साथ मैप किया और इसकी एक कीस्ट्रोक्स I को लगभग स्वचालित रूप से दबाया। मेरा मानना ​​है कि ReSharper के पास इंटरफ़ेस के प्रलेखन को सम्मिलित करने का विकल्प भी है, जब यह आपके लिए तरीकों को लागू करता है।

Answer 4

केवल इंटरफ़ेस। दोनों पर टिप्पणी करना दोहराव है और संभावना है कि कोड बदलने पर टिप्पणियों के दो सेट अंततः सिंक से बाहर निकल जाएंगे। कार्यान्वयन को "लागू करें MyInterface" के साथ टिप्पणी करें ... Doxygen जैसी चीजें डॉक्स उत्पन्न करेंगी जो डॉक में व्युत्पन्न डॉक्स को कार्यान्वयन के लिए वैसे भी शामिल करती हैं (यदि आप उन्हें सही तरीके से सेट करते हैं)।

Answer 5

हम सिर्फ इंटरफ़ेस पर टिप्पणी करते हैं, टिप्पणियों को व्युत्पन्न या आधार वर्ग / इंटरफ़ेस के साथ सिंक से बाहर निकलना इतना आसान है कि इसे केवल एक ही स्थान पर रखना अच्छा है।

हालाँकि ऐसा लगता है कि @ नाथ शायद एक स्वचालित प्रलेखन उपकरण का सुझाव दे रहे हैं जो चीजों को एक साथ रखने में मदद करता है (यदि आप इसका उपयोग करते हैं तो शांत लगता है)। यहाँ पर जहां परIIorkAndYouDontCare हैं, टिप्पणी देव के लिए है, इसलिए कोड में एक ही स्थान पसंद किया जाता है

Comments

स्वचालित नहीं, उपयोगकर्ता कार्रवाई की आवश्यकता है, दुर्भाग्य से।

— निकोलाईडेंट

Answer 6

वास्तविक कार्यान्वयन का उपयोग कैसे करें, यह जानने के लिए इंटरफ़ेस पर टिप्पणी करना पर्याप्त प्रलेखन होना चाहिए। केवल वही समय जो मैं टिप्पणियों को लागू करने के लिए जोड़ूंगा, यदि इसमें निजी कार्य हैं जो इंटरफ़ेस को संतुष्ट करने के लिए डाले गए हैं, हालांकि वे आंतरिक केवल टिप्पणियां होंगी और ऑनलाइन या ग्राहकों के लिए उपलब्ध दस्तावेज में नहीं दिखेंगी।

कार्यान्वयन सिर्फ इतना है कि, जब तक वे इंटरफ़ेस के अनुरूप नहीं होते हैं, तब तक उन्हें अलग से दस्तावेज़ करने की कोई आवश्यकता नहीं है।

Answer 7

मैंने एक उपकरण बनाया है जो <inheritdoc /> टैग के लिए समर्थन जोड़ने के लिए XML प्रलेखन फ़ाइलों को पोस्ट-प्रोसेस करता है।

हालांकि यह स्रोत कोड में Intellisense के साथ मदद नहीं करता है, यह संशोधित XML प्रलेखन फ़ाइलों को एक NuGet पैकेज में शामिल करने की अनुमति देता है और इसलिए संदर्भित NuGet पैकेजों में Intellisense के साथ काम करता है।

यह www.inheritdoc.io (मुफ्त संस्करण उपलब्ध) पर है।

Comments

ध्यान दें कि <inheritdoc /> सैंडकास्टल हेल्प फ़ाइल बिल्डर द्वारा भी समर्थित है, और यहां प्रलेखित है: ewsoftware.github.io/XMLCommentsGuide/html/… । बस देखा कि यह भी ऊपर उल्लेख किया गया था।

— ऑली

Answer 8

आप निश्चित रूप से दोनों पर टिप्पणी कर सकते हैं लेकिन फिर आपको दोनों बनाए रखने की समस्या है (जैसा कि पहले उल्लेख किया गया है)। हालांकि, इस दिन और उम्र में कोई भी खपत कोड वास्तव में IoC / DI का उपयोग करने वाला नहीं है और इंटरफ़ेस का उपयोग नहीं करता है? यह देखते हुए कि यदि आप केवल एक टिप्पणी करना चाहते हैं, तो मैं इंटरफ़ेस को टिप्पणी करने का सुझाव देना चाहूंगा। इस तरह से आपके कोड के उपभोक्ता को अच्छे इंटैलिजेंस संकेत मिलने की संभावना अधिक होगी।

Answer 9

सी # उपयोग:

इंटरफ़ेस इस तरह दिख सकता है:

    /// <summary>
    /// Helper class to access various properties for the current site.
    /// </summary>
    public interface ISiteHelper
    {
        /// <summary>
        /// Gets the site id of the current site
        /// </summary>
        /// <returns>The site id.</returns>
        int GetSiteID();
    }
}

कार्यान्वयन इस तरह दिख सकता है:

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
    /// <inheritdoc />
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}