सी # एक्सएमएल टिप्पणियां: एक्सएमएल टिप्पणियों में कितने <see ... /> संदर्भ उपयोगी हैं?

Question

हमारी कंपनी में हम अत्यधिक एक्सएमएल टिप्पणियां लिखते हैं। एक ठेठ विधि इस तरह से प्रलेखित है है करने के लिए किया जा:

/// <summary> 
/// Determines whether this <see cref="IScheduler"/> contains a specific <see cref="ISchedule"/>. 
/// </summary> 
/// <param name="schedule">The <see cref="ISchedule"/> to locate in this <see cref="IScheduler"/>.</param> 
/// <returns> 
/// Returns <see langword="true"/> if <paramref name="schedule"/> is found in this <see cref="IScheduler"/>; otherwise, <see langword="false"/>. 
/// </returns> 
bool Contains(ISchedule schedule); 

/// <summary> 
/// Removes and <see cref="IDisposable.Dispose"/>s the first occurrence of a specific <see cref="ISchedule"/> 
/// from this <see cref="IScheduler"/>. 
/// </summary> 
/// <param name="schedule">The <see cref="ISchedule"/> to remove from this <see cref="IScheduler"/>.</param> 
/// <exception cref="System.ArgumentNullException">Is thrown when the parameter schedule is null.</exception> 
/// <exception cref="System.ArgumentException">Is thrown when the <see cref="ISchedule"/> is not found in this <see cref="IScheduler"/> or was of the wrong type.</exception> 
void Remove(ISchedule schedule); 

आप लगभग हर संज्ञा है जो एक <see cref> टैग का उपयोग कर संदर्भित किया जा सकता देख सकते हैं।
मुझे यह बहुत अधिक लगता है। हमारी अधिकांश कोड फ़ाइलों को ऐसी टिप्पणियों के साथ उड़ाया जाता है। टिप्पणियां अनुभाग लगभग अपठनीय बनाता है।

आपको क्या लगता है? क्या आपको इस तरह के दस्तावेज कोड में पसंद है या नहीं?

सामान्य रूप से मुझे लगता है कि इस तरह के प्रश्न के लिए कोई काला/सफेद जवाब नहीं है, इसलिए मैंने इसे विकी बना दिया।

संपादित करें:
मेरा प्रश्न यह नहीं था कि देखें-रेफ-टैग स्वयं डिफ़ॉल्ट रूप से उपयोगी होते हैं। यह स्पष्ट है कि .chm फ़ाइल (या किसी अन्य प्रकार के जेनरेट किए गए डॉकू) में जेनरेट किए गए लिंक बहुत उपयोगी हैं। मेरा सवाल यह था कि टिप्पणियों में हर "लिंक करने योग्य" संज्ञा की हर घटना को टैग करना वाकई उपयोगी होता है।
हम हर रात डॉकू उत्पन्न करने के लिए सैंडकासल का उपयोग करते हैं। दुर्भाग्यवश यह अन्य डेवलपर्स द्वारा बहुत ही कम इस्तेमाल किया जाता है, लेकिन यह एक और मुद्दा है।

Answer 1

उन सभी का मुद्दा यह है कि जब पुस्तकालय के लिए HTML या CHM दस्तावेज़ उत्पन्न करने के लिए Sandcastle की तरह कुछ उपयोग किया जाता है, तो उन दस्तावेज़ों को ऑब्जेक्ट्स के बीच हाइपरलिंक नेविगेशन मिलता है। तो सवाल यह है कि, जब आप एमएसडीएन का उपयोग करते हैं, तो क्या आपको कक्षा के नाम पर क्लिक करने में सक्षम होने के लिए उपयोगी लगता है, क्या यह उस वर्ग के लिए सहायता पर नेविगेट करता है, या आप इसे कॉपी करने और खोज क्षेत्र में पेस्ट करने के साथ ठीक हैं?

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

Answer 2

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

मैं एक संपादक का उपयोग करने की अनुशंसा करता हूं जो आपको टिप्पणियां चालू और बंद करने की अनुमति देता है।

कुछ भाषाएं आपको चर और कार्यों पर मेटाडेटा के रूप में टिप्पणियां संग्रहीत करने देती हैं, जो एक अच्छा विकल्प है।

Answer 3

व्यक्तिगत रूप से, मुझे लगता है कि आपके पास थोड़ा सा ओवरबोर्ड है।

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

आपके मामले में, अपने व्यापार विशेष पुस्तकालयों भाषा आइटम संदर्भित कर रहे हैं, अर्थात्:

<see langword="true"/> 

मैं व्यक्तिगत रूप से लगता है कि अपने पुस्तकालय में अन्य संबंधित वस्तुओं के लिए हाइपरलिंक एक बहुत ही उपयोगी सुविधा है। यह आपकी उपयोगकर्ताओं के लिए मदद को और अधिक उपयोग करने में मदद करता है।

भाषा तत्वों के लिए हाइपरलिंक्स ऐसा कुछ है जो मुझे लगता है कि केवल भाषा की सहायता के भीतर ही मौजूद होना चाहिए। किसी तृतीय पक्ष लाइब्रेरी के मामले में, यह हर जगह लिंक डालकर संदेश को "गड़बड़" करता है। इससे अच्छे लिंक कम प्रभावी होते हैं, क्योंकि वे गंदगी में छिप जाते हैं।

मैं आपकी लाइब्रेरी में संबंधित कक्षाओं को जोड़ने का उदार उपयोग करने का सुझाव दूंगा। मैं बेस लाइब्रेरी कक्षाओं में हाइपरलिंक्स जोड़ने से बचूंगा, विशिष्ट उदाहरणों को छोड़कर जहां यह किसी कारण (दुर्लभ) के लिए विशेष रूप से उपयोगी है। "सत्य" और "IDisposable.Dispose", आदि से लिंक करना वास्तव में बहुत अधिक मूल्य नहीं जोड़ता है।

आधारभूत ढांचे को समझने के लिए अपने उपयोगकर्ता पर भरोसा करें, लेकिन उन्हें अपनी लाइब्रेरी के बारे में सिखाएं।

Answer 4

सीटीकेई ने कहा, यह हाइपरलिंकिंग के लिए बहुत उपयोगी है। हालांकि, अगर आप वास्तव में शिपिंग दस्तावेज नहीं भेज रहे हैं, तो वह टैगिंग दस्तावेज को पढ़ने के लिए लगभग असंभव बनाता है। उस स्थिति में, दस्तावेज़ीकरण (संपादित करें: आंतरिक) डेवलपर के लिए है, और यदि वह इसे पढ़ नहीं सकता है, तो आप अपना समय बर्बाद कर रहे हैं।

एक नियम के रूप में, मैं किसी प्रकार या सदस्य के पहले संदर्भ में जाता हूं, और बाकी को अनलिंक छोड़ देता हूं। यह टिप्पणियां बहुत साफ छोड़ देता है, और अभी भी सार्थक लिंकिंग प्रदान करता है।

Answer 5

जब आप विजुअल स्टूडियो के साथ काम कर रहे हों, तो आप WYSiWYG पढ़ने/लिखने के लिए CR_Documentor प्लगइन का उपयोग कर सकते हैं (यह मुफ़्त है, आप इसे here प्राप्त कर सकते हैं)। ऐसा लगता है कि जेनरेटेड हेल्प फॉर्म सैंडकासल या एनडीओसी है, लेकिन फ्लाई पर प्रस्तुत किया जाता है। यह वास्तव में उपयोगी है, और आपको कच्चे एक्सएमएल टिप्पणियों की परवाह नहीं है।