सी # /। नेट में अपवादों को कैसे प्रलेखित किया जाए

Question

मैं वर्तमान में एक छोटी रूपरेखा लिख ​​रहा हूं जिसका उपयोग कंपनी के भीतर अन्य डेवलपर्स द्वारा आंतरिक रूप से किया जाएगा।

मैं अच्छी इंटैलिजेंस जानकारी प्रदान करना चाहता हूं, लेकिन मुझे यकीन नहीं है कि कैसे अपवादों को फेंक दिया जाए।

निम्नलिखित उदाहरण में:

public void MyMethod1()
{
    MyMethod2();

    // also may throw InvalidOperationException
}

public void MyMethod2()
{
    System.IO.File.Open(somepath...); // this may throw FileNotFoundException

    // also may throw DivideByZeroException
}

मुझे पता है कि अपवादों के दस्तावेजीकरण के लिए मार्कअप है:

/// <exception cref="SomeException">when things go wrong.</exception>

मुझे समझ में नहीं आता है कि कोड के द्वारा फेंके गए अपवादों को दस्तावेज़ द्वारा कैसे कहा जाता है MyMethod1() ?

• क्या मुझे इसके द्वारा फेंके गए अपवादों का दस्तावेजीकरण करना चाहिए MyMethod2()
• क्या मुझे अपवादों को दस्तावेज़ में लाना चाहिए File.Open()?

संभावित अपवादों का दस्तावेजीकरण करने का सबसे अच्छा तरीका क्या होगा?

Comments

मुझे पता है कि यह बिल्कुल वैसा नहीं है जैसा आप पूछ रहे थे (और यह वास्तव में एक पुराना सवाल है), लेकिन एरिक लिपर्ट (Microsoft C # कंपाइलर और डिज़ाइन टीमों के प्रमुख डेवलपर) ने 4 प्रकार के अपवादों के बारे में एक ब्लॉग पोस्ट लिखा है, जो मुझे लगता है कि हर डेवलपर अपवाद हैंडलिंग कोड लिखते समय इस बारे में सोचना चाहिए: blogs.msdn.com/b/ericlippert/archive/2008/09/10/……

— javajavajavajavajava

@javajavajavajavajajava लिंक के लिए धन्यवाद - निश्चित रूप से पढ़ने लायक।

— अर्नोल्ड जोकस

मुझे लगता है कि यह एक वैध सवाल है क्योंकि यह बिल्कुल स्पष्ट नहीं है कि सी # में अपवादों को कैसे ठीक से दिखाया जाए और 50K के विचार यह दर्शाते हैं कि यह बहुत सारे लोगों के लिए भी स्पष्ट नहीं है। दूसरा सबसे अधिक वोट किया गया उत्तर बहुत उपयोगी है क्योंकि यह दस्तावेज़ को मौजूदा xmldocs का उपयोग करने के लिए दिखाता है। फिर से मतदान करना। यह "राय-आधारित" करीबी कारण वास्तव में बहुत उपयोगी प्रोग्रामिंग प्रश्नों को मार रहा है।

— एलेक्सी

Answer 1

आपको अपने कोड द्वारा फेंके जाने वाले हर अपवाद का दस्तावेजीकरण करना चाहिए, जिसमें आपके द्वारा कॉल की जाने वाली कोई भी विधि शामिल हो सकती है।

यदि सूची थोड़ी बड़ी हो जाती है, तो आप अपना स्वयं का अपवाद प्रकार बनाना चाहते हैं। उन सभी को पकड़ो जिन्हें आप अपने तरीके से सामना कर सकते हैं, उन्हें अपने अपवाद में लपेटें और उन्हें फेंक दें।

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

---

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

जिन लोगों के बारे में आप नहीं जानते, वे आपको जाने देना चाहते हैं। तेजी से विफल होने का यह प्रमुख - बेहतर है कि आपका ऐप एक ऐसी स्थिति में दुर्घटनाग्रस्त हो जाए जहां आप अपने डेटा को दूषित कर सकते हैं। दुर्घटना आपको बताएगी कि क्या हुआ और क्यों हुआ, जो उस अपवाद को "उन लोगों से बाहर निकालने में मदद कर सकता है, जिन्हें आप सूची के बारे में नहीं जानते"।

जिनके बारे में आप जानते हैं और जिनके बारे में कुछ नहीं कर सकते हैं, वे OutOfMemoryException जैसे अपवाद हैं। चरम मामलों में आप इस तरह के अपवादों को संभालना चाह सकते हैं, लेकिन जब तक आपके पास कुछ बहुत ही उल्लेखनीय आवश्यकताएं नहीं होती हैं, तब तक आप उन्हें पहली श्रेणी की तरह मानते हैं। क्या आप है लेकिन इसके कुछ अपवाद दस्तावेज़ के लिए? आप हर एक विधि पर OOMs का दस्तावेजीकरण करते हुए बहुत ही मूर्खतापूर्ण दिखेंगे, जो किसी वस्तु को नया बना देता है।

जिनके बारे में आप जानते हैं और कुछ कर सकते हैं वे हैं जिनके बारे में आपको दस्तावेज और लपेटने चाहिए।

आप यहां अपवाद हैंडलिंग पर कुछ और दिशानिर्देश पा सकते हैं ।

Comments

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

— एंड्रयू हरे

क्या आपका उत्तर अच्छा है, लेकिन यह वास्तव में दो उत्तर हैं जो एक दूसरे के विपरीत हैं। "आपके कोड द्वारा फेंके जा सकने वाले हर अपवाद का दस्तावेज़" और "वे जिनके बारे में आप जानते हैं और कुछ कर सकते हैं जिनके बारे में आपको दस्तावेज़ होना चाहिए"।

— tymtam

@ टायमेक: नोप। पहली छमाही ने सवाल का जवाब दिया "मुझे अपवादों को कैसे दस्तावेज़ करना चाहिए" दूसरे भाग ने "दस्तावेज़ों को क्या अपवाद देना चाहिए" के लिए स्पष्ट रूप से स्पष्ट जवाब दिया। पहला मतलब यह नहीं है कि आप हर अपवाद का दस्तावेजीकरण करते हैं जो संभवतः कभी भी हो सकता है। कुछ लोग बहुत अधिक शाब्दिक हैं, जिन्हें दूसरी छमाही की आवश्यकता थी।

@ मुझे लगता है कि आपकी बात यह हो सकती है कि यदि आप इसके बारे में कुछ कर सकते हैं, तो इसके बारे में कुछ भी क्यों न करें और इसे डॉक्यूमेंट करें? यह कहना अधिक सत्य हो सकता है कि "जिनके बारे में आप जानते हैं कि क्लाइंट कोड कुछ कर सकता है"। यह विरोधाभास को हटाता है, क्योंकि ये दस्तावेज़ के लिए आदर्श अपवाद हैं।

— मो।

अपवाद के रूप में आप 'जाने दो', आप हमेशा उन्हें कुछ निचले स्तर पर पकड़ सकते हैं जो उन्हें या कुछ और से जोड़ता है। तुम्हे पता हैं; बस प्रोग्राम को दुर्घटनाग्रस्त करने का एक उपयोगकर्ता-अनुकूल तरीका बना रहा है।

— Nyerguds

Answer 2

आपको मानक xml प्रलेखन का उपयोग करना चाहिए ।

/// <exception cref="InvalidOperationException">Why it's thrown.</exception>
/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod1()
{
    MyMethod2();
    // ... other stuff here
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod2()
{
    System.IO.File.Open(somepath...);
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
public void MyMethod3()
{
    try
    {
        MyMethod2();
    }
    catch (DivideByZeroException ex)
    {
        Trace.Warning("We tried to divide by zero, but we can continue.");
    }
}

इसे इस तरह से करने का मूल्य यह है कि आप ज्ञात अपवादों के प्रलेखन प्रदान कर सकते हैं जो हो सकते हैं। यदि आप दृश्य स्टूडियो का उपयोग कर रहे हैं और यह (या अन्य) आपको उन अपवादों के बाद याद दिला सकता है, जिनकी आप अपेक्षा कर सकते हैं, यह दस्तावेज अंतर्कलह में उपलब्ध है।

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

Comments

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

— इलुमिनाती

@SiranGinige आपका अनुभव गलत है।

— ग्रूज़

Answer 3

आप कई महान ऐड-इन्स का उपयोग करके अपनी प्रलेखन प्रक्रिया को आसान बना सकते हैं। उनमें से एक घोस्टडॉक है , जो विज़ुअल स्टूडियो के लिए एक मुफ्त ऐड-इन है जो एक्सएमएल-डॉक टिप्पणियों को उत्पन्न करता है। इसके अलावा, यदि आप ReSharper का उपयोग करते हैं , तो ReSharper के लिए उत्कृष्ट Agent Johnson Plugin पर एक नज़र डालें , जो फेंके गए अपवादों के लिए XML टिप्पणियाँ उत्पन्न करने के लिए एक विकल्प जोड़ता है।

अपडेट: ऐसा लगता है कि एज जॉनसन R # 8 के लिए उपलब्ध नहीं है, विकल्प के रूप में ReSharper के लिए असाधारण चेकआउट ...

चरण 1: घोस्टडोक XML टिप्पणी (Ctrl-Shift-D) उत्पन्न करता है, जबकि ReSharper के लिए एजेंट जॉनसन प्लगइन अपवाद के रूप में भी दस्तावेज का सुझाव देता है:

चरण 2: अपवाद दस्तावेज़ को जोड़ने के लिए ReSharper की शॉर्टकट कुंजी (Alt-Enter) का उपयोग करें:

चरण 2 http://i41.tinypic.com/osdhm

उम्मीद है की वो मदद करदे :)

Comments

टीनपिक लिंक टूटे हुए हैं।

— एनेव्स

Answer 4

जो मैं समझता हूं, <अपवाद> तत्व का उपयोग करने का उद्देश्य सजाने के तरीकों का उपयोग करना है, अपवाद नहीं:

/// <summary>Does something!</summary>
/// <exception cref="DidNothingException">Thrown if nothing is actually done.</exception>
public void DoSomething()
{
// There be logic here
}

अपवाद जिन्हें अन्य तरीकों से फेंका जा सकता है, जिन्हें बुलाया जाता है, उन तरीकों को पकड़ा, संभाला और प्रलेखित किया जाना चाहिए। अपवाद जो संभवतः .NET द्वारा फेंके जा सकते हैं, या आपके अपने कोड द्वारा स्पष्ट रूप से फेंके गए अपवादों को प्रलेखित किया जाना चाहिए।

जहाँ तक उससे अधिक विशिष्ट होने की बात है, शायद आप अपने स्वयं के अनुकूलित अपवादों को पकड़ और फेंक सकते हैं?

Answer 5

आपकी विधि के लिए अनुबंध का हिस्सा यह जांचना चाहिए कि पूर्व शर्तें मान्य हैं, इसलिए:

public void MyMethod2()
{
    System.IO.File.Open(somepath...); // this may throw FileNotFoundException
}

हो जाता है

/// <exception cref="FileNotFoundException">Thrown when somepath isn't a real file.</exception>
public void MyMethod2()
{
    FileInfo fi = new FileInfo( somepath );
    if( !fi.Exists )
    {
        throw new FileNotFoundException("somepath doesn't exists")
    }
    // Maybe go on to check you have permissions to read from it.

    System.IO.File.Open(somepath...); // this may still throw FileNotFoundException though
}

इस दृष्टिकोण के साथ, उन सभी अपवादों का दस्तावेज़ीकरण करना आसान है जिन्हें आप स्पष्ट रूप से फेंकने के लिए भी दस्तावेज़ के बिना हैं , जिन्हें फेंक दिया जा OutOfMemoryException सकता है, आदि।

Comments

निश्चित नहीं है कि उस चेक का क्या मतलब है यदि आप केवल उस अपवाद की नकल करने जा रहे हैं जो Openकॉल वैसे भी फेंक देगा (उल्लेख करने के लिए नहीं, जैसा कि आप ध्यान दें, कि एक दौड़ है और चेक सफलता की गारंटी नहीं देता है Open)। ।

— मैट एन्योर

@MattEnright दी, लेकिन मैं इस बिंदु को स्पष्ट करने के लिए एक छोटे से वंचित बना दिया है ...

— Rowland Shaw

Answer 6

आपको उन सभी अपवादों का दस्तावेजीकरण करना चाहिए जो संभवतः आपकी विधि द्वारा फेंके जा सकते हैं।

कार्यान्वयन विवरण को छिपाने के लिए, मैं MyMethod2 के कुछ अपवादों को स्वयं संभालने का प्रयास करूंगा।

यदि आप अपवाद को संभाल या हल नहीं कर सकते, तो आप उन्हें वापस लेने पर विचार कर सकते हैं। कॉल करने वाले के लिए अधिक अर्थपूर्ण अपवाद में अधिकतर पैक / लिपटा हुआ।

Answer 7

दरअसल, जैसा कि पहले ही उत्तर दिया जा चुका है, अपवादों का दस्तावेजीकरण करने का तरीका XML कमेंट्स का उपयोग कर रहा है।

प्लगइन्स के अलावा, आप स्थैतिक विश्लेषण टूल का भी उपयोग कर सकते हैं जिसे टीएफएस के साथ एकीकृत किया जा सकता है यह सुनिश्चित करने के लिए कि आपके पास अपवादित दस्तावेज हैं।

नीचे दिए गए लिंक में आप देख सकते हैं कि कैसे अपने तरीके से फेंक दिए गए अपवादों को प्रमाणित करने के लिए स्टाइलकॉप के लिए एक कस्टम नियम का निर्माण किया जा रहा है।

http://www.josefcobonnin.com/post/2009/01/11/Xml-Documentation-Comments-Exception-I.aspx http://www.josefcobonnin.com/post/2009/01/15/Xml-Documentation -Comments-अपवाद-II.aspx

सादर।

Answer 8

दस्तावेज़ आपके तरीके में अपवाद की उम्मीद करता है, आपके उदाहरण में मैं उपयोगकर्ता को यह बताना चाहूंगा कि यह विधि अपवाद नहीं मिली फ़ाइल को फेंक सकती है।

याद रखें कि यह कॉलर को सूचित करना है कि क्या अपेक्षा की जाए ताकि वे यह चुन सकें कि इससे कैसे निपटें।