language agnostic - एपीआई प्रलेखन और "मूल्य सीमा": क्या वे मैच करते हैं?




language-agnostic documentation (4)

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

@ माइक स्टोन:

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

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

अपने विचारों को खाना जोड़ने के लिए (और स्कॉट डोरेन के साथ जाना), मैं सिर्फ जावा 7 एनोटेशन के भविष्य पर ठोकर खाई

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

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

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

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

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

नोट: मैं कोड के भीतर टिप्पणियों के बारे में बात नहीं कर रहा हूं

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

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

नमूना:

मैं अक्सर क्या देखता हूं (बिना स्रोत कोड तक पहुंच):

/**
 * 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 () फ़ंक्शन के साथ एक पुस्तकालय का उपयोग करता हूं, तो मुझे यह अनुमान लगाने के लिए अक्सर यह एपीआई दस्तावेज पढ़ने की ज़रूरत नहीं है कि यह क्या करता है। लेकिन मुझे यह सुनिश्चित करने की आवश्यकता है कि इसका उपयोग कैसे करना है

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

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

यह उपयोग को प्रभावित कर सकता है या चेक या अनचेक अपवादों के लिए नहीं।

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


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

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

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


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

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


प्रश्न 1

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

लगभग नहीं।

प्रश्न 2

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

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

टिप्पणियों जैसे @param aReaderNameRegexp filter in order to ... (can be null or empty) मुझे एक तरीका लगता है कि @param aReaderNameRegexp filter in order to ... (can be null or empty) अंदर इंसान की भाषा में अनुबंध द्वारा डिजाइन लागू किया जा सकता है।

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

प्रश्न 3

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

जावा भाषा में अनुबंध की सुविधा का कोई डिजाइन नहीं है, इसलिए आप Execption का उपयोग करने के लिए परीक्षा ले सकते हैं, लेकिन मैं इस तथ्य से सहमत हूं कि आपको पता होना चाहिए कि चेक और अनचेक किए गए अपवादों को कब चुनना है । संभवतः आप अनियंत्रित IllegalArgumentException उपयोग कर सकते हैं IllegalArgumentException , IllegalStateException , या आप इकाई परीक्षण का उपयोग कर सकते हैं, लेकिन बड़ी समस्या यह है कि दूसरे प्रोग्रामर से संवाद कैसे करना है कि ऐसा कोड डिजाइन द्वारा अनुबंध के बारे में है और इसे थोड़ा हल्का ढंग से बदलने से पहले अनुबंध के रूप में माना जाना चाहिए।





design-by-contract