XML दस्तावेज़ टिप्पणियों में मुझे क्या शामिल करना चाहिए?

Question

मैं अपने कोड को बेहतर बनाने के लिए एक बिंदु बनाने की कोशिश कर रहा हूं, खासकर जब यह वर्ग के सदस्यों पर एक्सएमएल टिप्पणियों की बात आती है, लेकिन अक्सर यह सिर्फ मूर्खतापूर्ण लगता है।

घटना संचालकों के मामले में, नामकरण सम्मेलन और पैरामीटर मानक और स्पष्ट हैं:

/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
    // actual code here...
}

मेरे पास अक्सर सरल गुण हैं जो (IMO) स्पष्ट रूप से नामित हैं ताकि सारांश बेमानी हो:

/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }

मुझे ऐसा नहीं लगता है कि इस तरह की टिप्पणी से ऐसी कोई जानकारी नहीं जुड़ती है जिसे घोषणा पहले ही बता नहीं देती है। सामान्य ज्ञान यह लगता है कि एक टिप्पणी जो कोड को दोहराती है, सबसे अच्छा अलिखित है।

जाहिर है, XML दस्तावेज़ नियमित इनलाइन कोड टिप्पणियों से अधिक है, और आदर्श रूप से 100% कवरेज होगा। मुझे ऐसे मामलों में क्या लिखना चाहिए ? यदि ये उदाहरण ठीक हैं, तो वे क्या मूल्य जोड़ते हैं जो मैं अब सराहना नहीं कर सकता हूं?

Comments

"और आदर्श रूप से 100% कवरेज होगा" - यह बहुत बहस योग्य है। मैं उन्हें केवल एक प्रकार के सार्वजनिक इंटरफ़ेस के लिए पसंद करता हूं, जो केवल अंतर्मुखी पॉपअप के लिए है, लेकिन निजी तरीकों के लिए वे बहुत ही IMO

— एड एस।

100% कवरेज निजी तरीकों पर लागू नहीं होता है, विशेषकर घटना संचालकों पर।

— SLaks

घोस्टडॉक मेरे लिए अपना दस्तावेज लिखता है। "क्या करता GetData()है" आप पूछते हैं? क्यों, Gets the dataजरूर!

— डेविन बर्क

@ जस्टिन: घोस्टडॉक काफी कूल लग रहा है। मैं इसे उठा सकता हूँ।

@ जस्टिन: आरजी, मुझे घोस्टडॉक से नफरत है - यह पहली बार में शानदार लगता है, लेकिन थोड़ी देर के बाद आपको पता चलता है कि आप ऑटो-जनरेट की गई टिप्पणियों को एक मील दूर कर सकते हैं, आमतौर पर जब आप पुराने कोड वापस आते हैं और यह पता लगाना होता है कि यह क्या करता है। हालांकि यह XML को सब कुछ टिप्पणी करना बहुत आसान बनाता है, यह सुनिश्चित नहीं करता है कि उन टिप्पणियों में कोई वास्तविक जानकारी है। घोस्टडॉक आपको एक अच्छा शुरुआती बिंदु देता है, लेकिन यह बहुत आसान है कि यह आलसी हो और कुछ भी छोड़ दें जिसे आप नाम और हस्ताक्षर पर ध्यान देकर समझ नहीं सकते थे।

— कीथ

Answer 1

XML डॉक्स टिप्पणियाँ सार्वजनिक सदस्यों के लिए अभिप्रेत हैं।

संकलक चेतावनी स्पष्ट रूप से इस में कहा गया है:

सार्वजनिक रूप से दृश्य प्रकार या सदस्य के लिए गुम XML टिप्पणी 'Type_or_Member'

यदि आप उन सदस्यों के नाम से पहले से ही स्पष्ट नहीं हैं, तो आपको केवल निजी सदस्यों के लिए एक्सएमएल टिप्पणियों को जोड़ना चाहिए।

Answer 2

यहाँ शुद्ध राय, इसलिए इसे ले लो इसके लायक है।

मुझे सतही xml टिप्पणियों से नफरत है । भूत प्रेत शैली वाले लोगों के लिए संदेह है कि केवल विधि / संपत्ति के नाम में रिक्त स्थान जोड़ें। इसमें कोई मूल्य नहीं जोड़ा गया है और बस वास्तविक कोड के बारे में मेरा विचार स्पष्ट है।

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

नहीं भी हो मुझे के अनावश्यक उपयोग पर शुरू कर दिया है this.और Me.।

एक साइड नोट के रूप में, मुझे विज़ुअल स्टूडियो एडिइन होना पसंद होगा जो मुझे xml टिप्पणियों की दृश्यता को टॉगल करने दें। (संकेत संकेत)

Comments

मुझे लगता है कि इस this.बात की शुरुआत हो सकती है क्योंकि किसी कारण से Microsoft के आधिकारिक दिशानिर्देशों ने स्थानीय चर और उदाहरण privateचर के लिए सटीक नामकरण सम्मेलन का उपयोग करने की सिफारिश की थी । यह एक बहुत ही त्रुटिपूर्ण शैली है, IMO - कुछ मामलों में आप StackOverflowExceptionसंपत्ति setएस में एक से दूर एक मोटी उंगली हैं या MyProperty = MyProperty;एक निर्माता के बजाय एक क्षेत्र को शून्य के लिए इनिशियलाइज़ किया जा सकता है, और यहां तक ​​कि m_अधिकांश समय Microsoft आंतरिक रूप से उपयोग करना जारी रखता है ।

— jrh

Answer 3

एक सार्वजनिक सदस्य पर XML दस्तावेजों को काफी क्रियात्मक और पूर्ण होना चाहिए, जैसा कि @SLaks ने उल्लेख किया है।

हालांकि, वे वास्तव में निजी, संरक्षित या आंतरिक सदस्यों पर उपयोगी हो सकते हैं क्योंकि विज़ुअल स्टूडियो इंटेलीसेंस को पॉप्युलेट करेगा और XML डॉक्स टिप्पणियों के साथ टूलटिप्स की मदद करेगा।

इस का मतलब है कि:

// describe what this does
private void DoSomething() 
{
    // or describe it here...

पूरी तरह से पर्याप्त दस्तावेज हो सकता है, लेकिन:

/// <summary>describe what this does</summary>
private void DoSomething() 
{

अपने कोड में कहीं और से देखना बहुत आसान होगा।

आम तौर पर सार्वजनिक XML टिप्पणियों पर मैं एपीआई के कुछ बाहरी उपयोगकर्ता के लिए लिख रहा हूं, और आंतरिक XML टिप्पणियों पर मैं अपनी टीम पर या अन्य लोगों के लिए लिख रहा हूं।

पैरामीटर विवरण को छोड़ना शायद पूर्व के लिए एक बुरा विचार है और बाद के लिए ठीक है।

मैं (सार्वजनिक एपीआई डॉक्स में विशेष रूप से) हमेशा शामिल करूंगा कि क्या getया setगुणों पर:

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
{ 
    get { return SelectedItem != null; } 
}

यह स्पष्ट नहीं है कि क्या C # के इंटैलिजेंस से है getया setउपलब्ध है, लेकिन इसे XML कमेंट पर डालने का मतलब होगा कि आप टूलटिप से एक नज़र में बता सकते हैं।

Comments

निर्भर करता है। क्या आप एक है, तो public getलेकिन एक internal setएक संपत्ति के रूप में? आप इसे कैसे टिप्पणी करते हैं? :-)

— गिलियूम '

@Guillaume XML टिप्पणी सार्वजनिक होने के बाद से मैं getXML में सिर्फ दस्तावेज़ के साथ जा रहा हूँ और setनियमित //टिप्पणियों के साथ दस्तावेज़ करूँगा ।

— कीथ