आप अनचेक अपवाद कैसे दस्तावेज़ करते हैं?

Question

उसकी प्रभावी जावा में यहोशू बलोच लिखते हैं:

"प्रत्येक अनियंत्रित अपवाद है कि एक विधि फेंक कर सकते हैं दस्तावेज़ के लिए जावाडोक @throws टैग का प्रयोग करें, लेकिन कीवर्ड फेंकता विधि घोषणा में अनियंत्रित अपवाद शामिल करने के लिए उपयोग नहीं करते हैं । "

खैर कि वास्तव में उचित लगता है, लेकिन कैसे पता लगाने के लिए, क्या अनियंत्रित अपवाद मेरी विधि फेंक कर सकते हैं?

के एक के बाद वर्ग की सोचते हैं:

public class FooClass { 

    private MyClass[] myClass; 

    /** 
    * Creates new FooClass 
    */ 
    public FooClass() { 
     // code omitted 
     // do something with myClass 
    } 

    /** 
    * Performs foo operation.<br /> 
    * Whatever is calculated. 
    * @param index Index of a desired element 
    * @throws HorribleException When something horrible happens during computation 
    */ 
    public void foo(int index) { 
     try { 
      myClass[index].doComputation(); 
     } catch (MyComputationException e) { 
      System.out.println("Something horrible happened during computation"); 
      throw new HorribleException(e); 
     } 
    } 
} 

अब, मैं HorribleException दस्तावेज है, लेकिन यह काफी स्पष्ट है, कि foo विधि भी अनियंत्रित java.lang.ArrayIndexOutOfBoundsException फेंक कर सकते हैं। कोड जितना जटिल होगा, सभी अनचेक अपवादों के बारे में सोचना मुश्किल है कि विधि फेंक सकती है। मेरा आईडीई मुझे बहुत मदद नहीं करता है और न ही कोई उपकरण करता है। चूंकि मुझे इसके लिए कोई उपकरण नहीं पता है ...

आप इस तरह की स्थिति से कैसे निपटते हैं?

Answer 1

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

इस विशेष मामले में, मैं ArrayIndexOutOfBoundsException को पर अपने कोड पर एक बग के रूप में खाता हूं और मैं कोड को ठीक से फेंक दूंगा कि यह कभी फेंकता नहीं है। अर्थात। यदि सरणी इंडेक्स रेंज में है और तदनुसार एक अपवाद फेंक कर एक चेक जोड़ें- जिसमें आप दस्तावेज़ करते हैं- या वैकल्पिक पथ लेते हैं।

Answer 2

आपके द्वारा पोस्ट किया गया उद्धरण, यदि आप आदर्श प्रोग्रामर बनना चाहते हैं तो आपको केवल कुछ ध्यान रखना होगा। प्रोग्रामिंग यह नहीं सोच रहा है कि "क्या गलत हो सकता है", लेकिन ऐसा लगता है कि कुछ बेहतरीन तरीका कैसे करें और इसे कैसे करें। यदि यह एक निजी परियोजना है, तो बस लिखें कि विधि क्या करती है।

• विधि दस्तावेज़ नहीं है:

  हालांकि, वहाँ तीन संभावित हल हैं।

• अपने कोड के एक मिनट के बारे में सोचें और पता लगाएं कि सबसे आम संभव अनचेक अपवाद क्या हो सकता है। उन्हें जावा-डॉक में जोड़ें। और यदि आप एक नए से मुठभेड़ करते हैं, तो पता लगाएं कि समस्या क्या है और इसे संभावित अपवाद के रूप में जोड़ें।
• संभव अपवाद और दस्तावेज़ के बारे में परवाह नहीं है केवल अपवाद आप विधि शरीर में फेंक (जैसे: if (obj == null) { throw new NullPointerException(); })।

Answer 3

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

ArrayIndexOutOfBoundsException कोड समीक्षा के साथ पता लगाएगा। आपके नमूना कोड में हमारे लक्ष्यों को एक ArrayIndexOutOfBoundsException के बजाय एक अवैधArgumentException फेंकने की आवश्यकता है। इसका दस्तावेज परीक्षण सर्वर से मिलेगा।

ArrayIndexOutOfBoundsException FindBugs में एक चेतावनी हो सकती है। किंतु मुझे यकीन नहीं है।

Answer 4

केवल वही दस्तावेज जो आप स्वयं फेंक रहे हैं।

इस मामले में, मैं एक सूचकांक सीमा के लिए जाना चाहते हैं की जाँच करें और अपने खुद के अपवाद: throw IllegalArgumentException("Index must be smaller than " +myClass.length + ", but is: " + index) और फिर JavaDoc में दस्तावेज़ IllegalArgumentException।

Answer 5

कोड जितना अधिक जटिल हो जाता है, सभी अनचेक अपवादों के बारे में सोचना कठिन होता है जो विधि फेंक सकती है।

आप एक समस्या कहाँ देखते हैं, मैं एक बहुत अच्छा अपने उदाहरण में सरल अपने कोड रखने के लिए ;-)

कारण देखते हैं, मैं ArrayIndexOutOfBoundsException दस्तावेज़ के लिए सुझाव देना चाहेंगे। सिर्फ इसलिए कि किसी व्यक्ति के पास आपके लिए खराब पैरामीटर देने पर कुछ हो सकता है, और इसे कहीं लिखा जाना चाहिए: "यदि आपने एक अवैध सरणी अनुक्रमणिका दी है, तो आपको ArrayIndexOutOfBoundsException मिलेगा। उदाहरण के लिए, String#charAt() विधि दस्तावेज़ यह फेंक सकता है IndexOutOfBoundException यदि सूचकांक मान्य नहीं है।

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