जावा विधि के दस्तावेज़ (सरल) पूर्व शर्त कैसे करें?

Question

अक्सर ऐसा होता है कि एक विधि अपने तर्कों पर बाधा लगाती है जिसे टाइप सिस्टम द्वारा वर्णित नहीं किया जा सकता है। उदाहरण के लिए, एक विधि की आवश्यकता हो सकती है कि कुछ तर्क गैर-शून्य हो, या कुछ int-टाइप किए गए तर्क सकारात्मक हो। यहां तक ​​कि अधिक जटिल पूर्व शर्त भी हो सकती है, उदाहरण के लिए कि एक निश्चित विधि पहले कहा जाता था, या कुछ निश्चित स्थिति में एक निश्चित वस्तु है। जावाडोक में इसे दस्तावेज करने का सबसे अच्छा तरीका क्या है?

उदाहरण के लिए, मैं निम्नलिखित सार्वजनिक पुस्तकालय समारोह है, जहां तर्क नकारात्मक नहीं हो सकता है लगता है:

public void foo(int bar) { 
    if (bar < 0) { 
     throw new IllegalArgumentException("Negative bars cannot be food."); 
    } 
    ... 
} 

मैं इस तरह से इस दस्तावेज़ के लिए चाहते हैं कि यह के बाकी हिस्सों से "बाहर खड़ा है" प्रलेखन पाठ ताकि दस्तावेज पाठकों को तुरंत पता चले कि उन्हें कहां देखना है। वर्तमान में, मैं जावाडोक को throws खंड जोड़कर ऐसा करते हैं:

/** 
* Foos a bar. 
* @param bar the bar to be food 
* @throws IllegalArgumentException if bar is negative 
*/ 
public void foo(int bar) { 
    ... 

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

क्या जावाडॉक में इस तरह की चीजों को दस्तावेज करने के लिए कोई सर्वोत्तम प्रथा है? मैंने सोचा है:

• दस्तावेज़ीकरण पाठ में वर्णित करते हुए कि तर्क नकारात्मक है अगर विधि ने व्यवहार को अपरिभाषित किया है। हालांकि, यह वास्तव में बाहर खड़ा नहीं है, इसलिए यह कई लाइब्रेरी उपयोगकर्ताओं द्वारा याद किया जा सकता है।
• एनोटेशन का उपयोग (public void foo(@NonNegative int bar))। हालांकि, इसके लिए एनोटेशन का एक मानक सेट आदर्श होगा, और यह मानक सेट मौजूद नहीं है।

Answer 1

आपको अपने एपीआई के जावाडॉक्स पर भरोसा करने में संकोच नहीं लगता है कि यह आपके एपीआई के लिए दस्तावेज है। हालांकि मैं मानता हूं कि कुछ डेवलपर्स हमेशा अपनी चेतावनियों को अनदेखा कर देंगे, मुझे लगता है कि ऐतिहासिक रूप से जावाडॉक्स एपीआई का सही तरीके से उपयोग करने के तरीके पर पर्याप्त मार्गदर्शन प्रदान करने में पूरी तरह से पर्याप्त हैं। आप पागल हो सकते हैं सभी प्रकार के कस्टम Annotation एस, लेकिन अंत में लोग कभी भी आपके एपीआई को गलत तरीके से कार्यान्वित करेंगे।

यदि आप पहले से कहीं भी आगे बढ़ना चाहते हैं, तो आप कहीं भी self-documenting नामकरण सम्मेलनों को लागू कर सकते हैं। उदाहरण के लिए:

/** 
* Foos a positive bar. 
* @param positiveBar the non-zero,non-negative bar to be food 
* @throws IllegalArgumentException if bar is zero or negative 
*/ 
public void foo(int positiveBar) { 
    ... 

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

Answer 2

आप custom javadoc tags बना सकते हैं, अर्थात @pre@inv और @postपूर्व हालत के लिए, निवेश संबंधी निर्णय ariant और पद हालत।

इसके अलावा, यहोशू बलोच प्रभावी जावा द्वितीय संस्करण में तर्क है कि:

डॉक टिप्पणी विधि के पूर्व शर्त है, जो एक ग्राहक को लागू करने के लिए आदेश में बातें है कि सच हो रहे हैं के सभी गणना करना चाहिए यह, और इसकी पोस्टकंडिशन आमतौर पर, पूर्व शर्तों को अनचेक अपवादों के लिए @throws टैग द्वारा स्पष्ट रूप से वर्णित किया गया है; प्रत्येक अनचेक अपवाद एक पूर्व शर्त उल्लंघन के अनुरूप है। इसके अलावा, पूर्ववर्तीताओं को उनके @param टैग में प्रभावित पैरामीटर के साथ निर्दिष्ट किया जा सकता है।

उदाहरण: वापस करने के लिए तत्व की

@param सूचकांक सूचकांक; गैर नकारात्मक और कम इस सूची के आकार @throws से IndexOutOfBoundsException अगर सूचकांक सीमा से बाहर है होना चाहिए ({@code सूचकांक < 0 || सूचकांक> = this.size()})

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