एपीआई दस्तावेज और "मूल्य सीमाएं": क्या वे मेल खाते हैं?

Question

क्या आप अक्सर एपीआई दस्तावेज (उदाहरण के लिए 'सार्वजनिक कार्यों के' जावाडोक 'में देखते हैं) "मूल्य सीमा" के साथ-साथ क्लासिक दस्तावेज का विवरण भी देखते हैं?

नोट: मैं बात नहीं कर रहा बारे में comments within the code

द्वारा "मूल्य सीमा", मेरा मतलब है:

• है एक पैरामीटर एक शून्य मान (या एक खाली स्ट्रिंग, या समर्थन कर सकते हैं .. ।)?
• क्या 'वापसी मूल्य' शून्य हो सकता है या कभी शून्य नहीं हो सकता है (या "खाली" हो सकता है, या ...)?

नमूना:

क्या मैं अक्सर (स्रोत कोड के लिए उपयोग किए बिना) देखें:

/** 
* Get all readers name for this current Report. <br /> 
* <b>Warning</b>The Report must have been published first. 
* @param aReaderNameRegexp filter in order to return only reader matching the regexp 
* @return array of reader names 
*/ 
String[] getReaderNames(final String aReaderNameRegexp); 

मैं को देखने के लिए होगा चाहते क्या:

/** 
* Get all readers name for this current Report. <br /> 
* <b>Warning</b>The Report must have been published first. 
* @param aReaderNameRegexp filter in order to return only reader matching the regexp 
* (can be null or empty) 
* @return array of reader names 
* (null if Report has not yet been published, 
* empty array if no reader match criteria, 
* reader names array matching regexp, or all readers if regexp is null or empty) 
*/ 
String[] getReaderNames(final String aReaderNameRegexp); 

मेरा मुद्दा है:

जब मैं इसमें getReaderNames() फ़ंक्शन के साथ लाइब्रेरी का उपयोग करता हूं, तो मुझे यह अनुमान लगाने के लिए अक्सर एपीआई दस्तावेज़ पढ़ने की आवश्यकता नहीं होती है। लेकिन मुझे यह सुनिश्चित करने की ज़रूरत है कि इसका उपयोग कैसे करें।

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

संपादित करें:

यह प्रभावित कर सकते हैं checked or unchecked exceptions के लिए उपयोग या नहीं।

आपको क्या लगता है? मूल्य सीमा और एपीआई, क्या वे एक साथ हैं या नहीं?

Answer 1

मुझे लगता है कि वे एक साथ हैं लेकिन आवश्यक नहीं है एक साथ होने के लिए है। आपके परिदृश्य में, ऐसा लगता है कि यह समझ में आता है कि सीमाएं इस तरह से प्रलेखित होती हैं कि वे जेनरेट किए गए एपीआई दस्तावेज और इंटेलिजेंस में दिखाई देते हैं (यदि भाषा/आईडीई इसका समर्थन करती है)।

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

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

Answer 2

मुझे लगता है कि वे करते हैं, और हमेशा हेडर फ़ाइलों (सी ++) में टिप्पणियां डालते हैं।

वैध इनपुट/आउटपुट/रिटर्न टिप्पणियों के अतिरिक्त, मैं यह भी ध्यान देता हूं कि फ़ंक्शन द्वारा कौन से अपवादों को फेंक दिया जाना पसंद है (क्योंकि मैं अक्सर वापसी मूल्य का उपयोग करना चाहता हूं ... अच्छी तरह से मूल्य लौटाता हूं, मैं अपवाद पसंद करता हूं त्रुटि कोड से अधिक)

//File: 
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list 
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method. 
//Exceptions: 
//except::FileNotFound 
//except::InvalidFile 
//except::InvalidParams 
//except::CreationFailed 
Texture *GetTexture(const std::string &File); 

Answer 3

मुझे लगता है कि उन प्रकार की सीमा स्थितियां सबसे निश्चित रूप से एपीआई में हैं। हालांकि, मैं (और अक्सर करता हूं) एक कदम आगे जाता हूं और इंगित करता हूं कि उन शून्य मूल्यों का क्या अर्थ है। या तो मुझे लगता है कि यह एक अपवाद फेंक देगा, या मैं समझाता हूं कि सीमा मान कब पारित होने पर अपेक्षित परिणाम क्या हैं।

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

Answer 4

@ फ़ैयर लांसर: ठीक है! मैं अपवाद बारे में भूल गया, लेकिन मैं उन्हें देखने के लिए उल्लेख किया है, विशेष रूप से अनियंत्रित 'क्रम' अपवाद है कि यह सार्वजनिक विधि

@Mike स्टोन फेंक सकता है चाहते हैं:

आप भी मेहनती अद्यतन करने के लिए रहना होगा जब आप विधि के अर्थशास्त्र को बदलते हैं तो दस्तावेज़।

Mmmm मुझे यकीन है कि उम्मीद है कि सार्वजनिक API दस्तावेज़ बहुत कम अद्यतन जब भी कोई परिवर्तन पर है - कि समारोह के अनुबंध को प्रभावित करता है - जगह लेता है। यदि नहीं, तो उन API दस्तावेज़ों को पूरी तरह से ड्रॉप किया जा सकता है।

तुम्हारा विचार करने के लिए भोजन को जोड़ने के लिए (और @Scott डार्मैन साथ जाना), मैं बस पर the future of java7 annotations

ठोकर कि क्या करता है मतलब है? प्रलेखन में होने के बजाए, कुछ निश्चित 'सीमा स्थितियां' एपीआई में बेहतर होनी चाहिए, और उचित 'जोर' उत्पन्न कोड के साथ संकलन समय पर स्वचालित रूप से उपयोग की जानी चाहिए।

इस तरह, यदि एपीआई में '@ चेकफ़ोरनुल' है, तो फ़ंक्शन का लेखक इसे दस्तावेज भी नहीं कर सकता है! और यदि अर्थात् परिवर्तन, इसकी एपीआई उस प्रतिबिंब को प्रतिबिंबित करेगी (उदाहरण के लिए 'कोई और @ चेकफ़ोरनुल' नहीं)

इस तरह के दृष्टिकोण से पता चलता है कि 'सीमा परिस्थितियों' के लिए दस्तावेज एक अनिवार्य अभ्यास के बजाय अतिरिक्त बोनस है ।

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

Answer 5

प्रश्न 1

आप अक्सर API दस्तावेज़ों में दिखाई दे रही है "मूल्य सीमा" के साथ-साथ क्लासिक प्रलेखन का वर्णन (उदाहरण के लिए 'सार्वजनिक कार्यों के जावाडोक' के रूप में)?

लगभग कभी नहीं।

प्रश्न 2

मेरी केवल चिंता जब मैं इस समारोह का उपयोग करना चाहते है: मैं मानकों के कार्यकाल में क्या उम्मीद और मान करना चाहिए? बस इतना ही मैं सुरक्षित रूप से सेटअप करने के लिए मेरी मापदंडों पता करने के लिए और सुरक्षित रूप से वापसी मान का परीक्षण, फिर भी मैं लगभग API दस्तावेज़ों में जानकारी उस तरह कभी नहीं की जरूरत है ...

अगर मैं एक समारोह के लिए इस्तेमाल किया ठीक से मुझे नहीं उम्मीद करेंगे प्रोग्राम के किसी अन्य (कभी-कभी बहुत दूर) भाग में RuntimeException विधि या RuntimeException द्वारा फेंक दिया गया है।

टिप्पणियाँ @param aReaderNameRegexp filter in order to ... (can be null or empty) की तरह मेरे लिए Javadoc अंदर एक मानव किया जा रहा है भाषा में Design by Contract लागू करने के लिए एक तरह से लगता है।

डिजाइन को लागू करने के द्वारा अनुबंध, iContract द्वारा इस्तेमाल किया गया था अब JcontractS में पुनर्जीवित जावाडोक उपयोग करके, आप मानव से किया जा रहा भाषा की तुलना में अपरिवर्तनशीलताओं, पूर्व शर्त, postconditions निर्दिष्ट करते हैं, अधिक औपचारिक तरीके से देते हैं।

प्रश्न 3

यह जाँच या अनियंत्रित अपवाद के लिए उपयोग या नहीं प्रभावित कर सकते हैं। आपको क्या लगता है? मूल्य सीमा और एपीआई, क्या वे एक साथ हैं या नहीं?

जावा भाषा अनुबंध सुविधा के द्वारा एक डिजाइन नहीं है, तो आप Execption का उपयोग करने के लिए परीक्षा हो सकती है, लेकिन मैं सच है कि आप When to choose checked and unchecked exceptions के बारे में जागरूक होना जरूरी है कि के बारे में आप के साथ सहमत हैं। शायद आप अनचेक IllegalArgumentException, IllegalStateException का उपयोग कर सकते हैं, या आप यूनिट परीक्षण का उपयोग कर सकते हैं, लेकिन बड़ी समस्या यह है कि अन्य प्रोग्रामर से संवाद कैसे करें कि इस तरह के कोड अनुबंध द्वारा डिज़ाइन के बारे में हैं और इसे बहुत हल्के ढंग से बदलने से पहले अनुबंध के रूप में माना जाना चाहिए।