क्या एपीआई के सभी सार्वजनिक तरीकों को दस्तावेज किया जाना चाहिए?

Question

"लाइब्रेरी" टाइप क्लास लिखते समय, क्या जावा में हमेशा मार्कअप दस्तावेज (यानी जावाडोक) लिखना बेहतर लगता है या मान लें कि कोड "स्वयं-दस्तावेज" हो सकता है? उदाहरण के लिए, दिए गए निम्न विधि ठूंठ:

/** 
* Copies all readable bytes from the provided input stream to the provided output 
* stream. The output stream will be flushed, but neither stream will be closed. 
* 
* @param inStream an InputStream from which to read bytes. 
* @param outStream an OutputStream to which to copy the read bytes. 
* @throws IOException if there are any errors reading or writing. 
*/ 
public void copyStream(InputStream inStream, OutputStream outStream) throws IOException { 
    // copy the stream 
} 

जावाडोक स्वयं-सिद्ध, और शोर है कि बस अगर funcion बिल्कुल बदल गया है अपडेट करने की आवश्यकता हो रहा है। लेकिन धारा को बंद करने और बंद करने के बारे में वाक्य मूल्यवान नहीं हो सकता है।

एक) हमेशा दस्तावेज़
ख) दस्तावेज़ कुछ भी है कि स्पष्ट
सी नहीं है) (कभी नहीं दस्तावेज़ कोड खुद के लिए बात करनी चाहिए)

:

तो, जब एक पुस्तकालय लेखन, यह सबसे अच्छा करने के लिए है!

मैं आमतौर पर ख का उपयोग करें), अपने आप (के बाद से कोड स्वयं का दस्तावेजीकरण अन्यथा) हो सकता है ...

Answer 1

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

Answer 2

ए) हमेशा दस्तावेज़।

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

Answer 3

मैं पूरी तरह से चुनता हूं क्योंकि जब मैं कक्षा की जांच करता हूं तो मुझे दस्तावेज सार्वजनिक तरीकों (जावडोक या इसी तरह) देखना पसंद है। यह कुछ चीजों को थोड़ा स्पष्ट बनाता है। लेकिन अपने स्वयं के लिए प्रत्येक।

Answer 4

प्रत्येक सार्वजनिक विधि को दस्तावेज किया जाना चाहिए।

Answer 5

यह वह जगह है जहां मैं आम तौर पर दस्तावेज के बारे में "दोनों तरह से चढ़ाई करता हूं" मंत्रों के बारे में बताता हूं जब आपके बॉस ने आपको केवल पूछताछ की है ... हाल ही में मैंने अपनी धुन बदल दी है। मुझे लगता है कि यह महत्वपूर्ण है जब आप ओपन-सोर्स प्रोजेक्ट पर काम कर रहे हों, प्रत्येक पुस्तकालय को सामान्य रूप से बुलाया जा सकता है, या समय से पहले पता है कि किसी और को इंटरफेस के साथ मिलकर काम करना होगा प्रदान कर रहे हैं

दस्तावेज़ीकरण बनाए रखने योग्य कोड के लिए बनाता है, लेकिन, किसी भी चीज़ की तरह, आप इसे अधिक कर सकते हैं और टिप्पणियां जोड़ने और पीओडी और विकीज़ लिखने में समय व्यतीत कर सकते हैं जब आपको सुविधाओं को जोड़ने और यूनिट परीक्षण पास करने के लिए काम करना चाहिए। इसे Agile Manifesto में संबोधित किया गया है (यानी: आमने-सामने संचार दस्तावेज़ीकरण से बेहतर है और इसलिए इंटरफेस विधियों की सीढ़ी पर)।

Answer 6

क)

यदि यह एक विधि है, वहाँ हमेशा कुछ छोटे विवरण है कि कोई फर्क नहीं है, उदाहरण के लिए जिन्हें आप फ्लशिंग के बारे में और धाराओं को बंद करने प्रदान की है। उदाहरण के लिए एक विधि "स्ट्रिंग getFileExtension (स्ट्रिंग फ़ाइल नाम)" प्रलेखन की आवश्यकता नहीं है, लेकिन क्या होगा यदि "फ़ाइल नाम" में कोई एक्सटेंशन नहीं है? वह जवाब दस्तावेज किया जाना चाहिए।

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

Answer 7

क)

दूसरों के रूप में उल्लेख किया है, तो आप प्रलेखन उत्पन्न कर सकते हैं और यह रखरखाव के साथ मदद करता है।

इसके अलावा, इंटेलिसेंस लाभ यह बताते हुए कि विधि/संपत्ति क्या है/है।

Answer 8

क)

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

Answer 9

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

एपीआई का एक अच्छा उदाहरण Java API Specification है। दस्तावेज़ के शीर्षक से नोटिस कि यह विनिर्देश है। मेरा मानना ​​है कि एक दस्तावेज इसे विनिर्देश के रूप में मानने के लिए पर्याप्त होना चाहिए।

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

clearAutoscroll

protected void clearAutoscroll()

clear autoscrolling 

कुछ भी नहीं है एक API कि uninformative है के लिए दस्तावेज़ की तुलना में अधिक परेशानी होती है, इस तरह। सबसे बुरी बात यह है कि प्रदान की गई जानकारी भी एक वाक्य नहीं है! सुनिश्चित करें कि सभी सार्वजनिक क्षेत्रों और विधियों के लिए प्रदान किया गया दस्तावेज पर्याप्त जानकारीपूर्ण है कि लाइब्रेरी के उपयोगकर्ता सूचित होने के बजाय परेशान नहीं होते हैं।

Answer 10

तो, मेरी राय है कि दूसरों का उपयोग आप एक API विकसित कर रहे हैं के लिए, यह हर विधि, संपत्ति के इरादे के रूप में स्पष्ट होना चाहिए, आदि है

मैं एक को देखने के लिए सक्षम होना चाहिए विधि और पता:

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

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

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

बस मेरे दो सेंट।

Answer 11

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

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

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

Answer 12

हमेशा दस्तावेज़।

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

इसके अलावा दस्तावेज़ीकरण की पूर्णता के लिए।

Answer 13

तोता के लिए खेद है, लेकिन हमेशा दस्तावेज़।

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

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

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

Answer 14

बी) सब कुछ दस्तावेज जो स्पष्ट नहीं है, या जब संदेह में है। इस मामले में:

/** Copies all readable bytes from inStream to outStream. outStream will be flushed, 
* but neither stream will be closed. 
*/ 

आप पहले से ही लिखा है कि inStream एक InputStream है, और जैसा कि आप पहले से ही समारोह की टिप्पणी

में ऐसा आप यह है कि यह अपने आप ही टिप्पणी में बाइट्स पढ़ने के लिए उद्देश्य से निर्दिष्ट करने के लिए की जरूरत नहीं है

Answer 15

केवल उन्हीं विधियों को दस्तावेज करें जिन्हें आप लोगों को उपयोग करने में सक्षम होना चाहते हैं, और प्रभावी ढंग से उपयोग करें।