इंटरफ़ेस कार्यान्वयन पर डुप्लिकेटिंग प्रलेखन अच्छा या बुरा ओवरराइड करता है?

Question

तो हमारे पास एक इंटरफ़ेस है जैसे

/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  void Create(Foo foo);
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  void Bar();
}

हाल ही में, हमने एक प्रलेखन कहानी निभाई जिसमें यह सुनिश्चित करना और सुनिश्चित करना शामिल था कि ऊपर की तरह बहुत सारे XML दस्तावेज़ हैं। यह हालांकि प्रलेखन के बहुत दोहराव का कारण बना। उदाहरण कार्यान्वयन:

/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  public void Create(Foo foo)
  {
    //insert code here
  }
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  public void Bar()
  {
    //code here
  }
}

जैसा कि आप देख सकते हैं कि विधि प्रलेखन इंटरफ़ेस से एक सीधा चीर है।

बड़ा सवाल यह है कि क्या यह बुरी बात है? मेरी आंत मुझे दोहराव के कारण हां कहती है, लेकिन फिर शायद नहीं?

इसके अलावा, हमारे पास overrideकार्यों और virtualकार्यों के साथ अन्य समान प्रलेखन दोहराव है।

क्या यह बुरा है और इससे बचना चाहिए, या नहीं? क्या यह सब सार्थक भी है?

Comments

यदि आप Resharper का उपयोग करते हैं, तो आप टिप्पणियों को केवल कार्यान्वयन में बदल सकते हैं और फिर "Pull members up" का उपयोग करके इंटरफ़ेस को अपडेट कर सकते हैं।

— भंवर

मैं ऐसा करता हूं, लेकिन शायद इसलिए कि मैं बाहरी उपकरणों का उपयोग करने में बहुत अच्छा नहीं हूं और किसी विशेष प्रकार की चीज़ के साथ क्या कर सकता हूं यह देखने के लिए इंटरफ़ेस के हेडर फ़ाइल पर नेविगेट करना पसंद करता हूं (यह सी और सी ++ के लिए है जो अलग हैं स्रोत फ़ाइल से हेडर की धारणा)। इसे थोड़ा दोहराव मिलता है, लेकिन मैं तरीकों को ओवरराइड करने वाले ठोस वर्ग से संबंधित अधिक विशिष्ट विवरणों को जोड़ने के अवसरों को खोजने की कोशिश करता हूं, जैसे मुझे यह पसंद है और मेरे पास एक ओसीडी चीज है जहां मुझे लगता है कि मैं कुछ महत्वपूर्ण छोड़ दिया है अगर मैं नहीं करता हूं हेडर फ़ाइल में हर फ़ंक्शन के लिए टिप्पणियां देखें।

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

Answer 1

सामान्य तौर पर, मैं केवल कार्यान्वयन के तरीकों में नए दस्तावेज़ जोड़ूंगा यदि उस कार्यान्वयन के बारे में कुछ विशिष्ट है जिसका उल्लेख किया जाना चाहिए।

Javadoc में आप अन्य तरीकों से लिंक कर सकते हैं, जो आपको इंटरफ़ेस में विधि प्रलेखन के कार्यान्वयन में लिंक बनाने की अनुमति देगा। मुझे लगता है कि यह .Net में कैसे किया जाता है (यह मेरे ऑनलाइन दस्तावेज़ को पढ़ने के आधार पर है, न कि मेरे स्वयं के अनुभव के आधार पर):

/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  void Create(Foo foo);
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  void Bar();
}

/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
  /// <summary>
  /// <see cref="ICreatesFoo.Create(Foo)"/>
  /// </summary>
  public void Create(Foo foo)
  {
    //insert code here
  }
  /// <summary>
  /// <see cref="ICreatesFoo.Bar()"/>
  /// Also Note: Implementation of Bar() in FastFooCreator
  /// requires a minimum of 512 MB RAM to Bar the Foo. 
  /// </summary>
  public void Bar()
  {
    //code here
  }
}

<see/>तत्व के लिए प्रलेखन : http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

Comments

एक विरासत वाले वर्ग में XML डॉक्स को ओवरराइड करने के बारे में कैसे? मान लें कि मैं एक उप-वर्ग बनाता हूं Collection<T>और इसकी Countसंपत्ति XML डॉक्स को ओवरराइड करना चाहता हूं ।

— शमी