प्रलेखन पर उदाहरणों को प्राथमिकता दें। क्या यह एक व्यवहारिक समस्या है?

Question

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

जब भी यह सीधा या गूढ़ या सिर्फ सादा उबाऊ नहीं होता है तो मैं जानबूझकर प्रलेखन / एपीआई से बचता हूं। मुझे प्रोग्रामिंग शुरू किए हुए कई साल हो चुके हैं और अब मुझे लगता है कि मुझे अपने तरीके से संभलने की जरूरत है क्योंकि मुझे अब एहसास हुआ कि मैं क्रिप्टोकरंसी / मुश्किल दस्तावेज पढ़ने से बचकर ज्यादा नुकसान पहुंचा रहा हूं क्योंकि यह अभी भी आधिकारिक तौर पर उदाहरणों से लाख गुना बेहतर है। प्रलेखन में किसी भी उदाहरण से अधिक कवरेज है। यह समझने के बाद भी कि उदाहरणों को सीखने के लिए "प्राथमिक" स्रोत के बजाय "जोड़ा" मान के रूप में माना जाना चाहिए।

मैं एक प्रोग्रामर के रूप में इस बुरी आदत को कैसे तोड़ सकता हूं या क्या मैं उखाड़ फेंक रहा हूं?

Comments

मुझे नहीं लगता कि यह एक बुरी आदत है। मैं हमेशा उदाहरणों से शुरू करता हूं और फिर आवश्यकतानुसार दस्तावेज पर पढ़ता हूं।

— कप्पन

a million times better than examples as the official documentation has more coverage- हमेशा नहीं, मैंने अतीत में कुछ महान

— अनिर्दिष्ट

प्रलेखन को उदाहरणों के साथ अवधारणाओं को संप्रेषित करना चाहिए। मैं आमतौर पर डॉक्स पर विचार करता हूं जो दस्तावेज़ में विफल नहीं होते हैं ।

— 15

Answer 1

उदाहरणों पर वरीयता में भरोसा करने की आदत में कुछ भी गलत नहीं है: आपके लिए, यह आपके उत्तर पाने का सबसे तेज़ तरीका है। इसके अलावा, उदाहरण दृश्य हैं। पाठ के पैराग्राफ को पढ़ने और अपनी आवश्यक जानकारी निकालने के बजाय नेत्रहीन उदाहरण को पार्स करना आसान है।

उदाहरण:

उत्पादों को सूचीबद्ध करने के लिए, किसी को नियंत्रक Indexकी कार्रवाई का उपयोग करना चाहिए Products, यह देखते हुए कि GETयहां केवल संभव क्रिया है (देखें [उत्पादों को प्रभावित करना] डेटाबेस से उत्पादों को बनाने, संशोधित करने और हटाने के लिए उपयोग की जाने वाली क्रियाओं के बारे में अधिक जानकारी के लिए)।

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

आप स्टॉक में मात्रा को ताज़ा करने के लिए सेवा को बाध्य करना चाह सकते हैं। यह एक को सेट करके किया जाता है refresh-quantities।

विस्तृत है, लेकिन उबाऊ और मुश्किल से पठनीय है। तथ्य यह है कि आप लिंक का पालन करने की जरूरत चीजों को और भी बदतर बना देता है। यदि हम कुछ नमूनों को जोड़ते हैं, तो यह समझना बहुत आसान हो जाता है:

GET Products / Index /
GET Products / Index / 12345 /
GET Products / Index /? Skip = 100 & take = 20
GET Products / Index /?
Category = 12 GET Products / Index /? Price = 0..39.90
GET Products / Index /? श्रेणी = 12 & छोड़ = 100 और ले = 20

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

जब आप जानते हैं कि आपको दस्तावेज़ पढ़ना चाहिए?

हर बार एपीआई या पुस्तकालय आपके द्वारा अपेक्षित व्यवहार नहीं कर रहा है। उदाहरण के लिए, आप नमूना लेते हैं और करते हैं:

उत्पाद प्राप्त करें / सूचकांक /? छोड़ें = 6000 और ले = 3000

किसी कारण से, यह 3 000 से कम वस्तुओं को लौटाता है, जबकि आपके डेटाबेस में बीस हजार से अधिक उत्पाद हैं। यहां, एपीआई आपकी अपेक्षा के अनुरूप व्यवहार नहीं कर रहा है, इसलिए विस्तृत दस्तावेज पढ़ने के लिए यह एक अच्छा समय है।

Comments

एकदम सही समझ में आता है। हमेशा उदाहरण के लिए मार्ग प्रशस्त होने पर भी दस्तावेज पर वापस जाएं!

— user6123723

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

— एमी ब्लेंकशिप

Answer 2

प्रलेखन द्वारा प्रदान की गई जानकारी तीन कैटगेरी में पड़ती है:

• विधि।
• संदर्भ।
• विशेषज्ञ ज्ञान।

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

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

मैं एक प्रोग्रामर के रूप में इस बुरी आदत को कैसे तोड़ूं या क्या मैं सोच के ऊपर हूं? साथी प्रोग्रामर से किसी भी ज्ञान की सराहना की जाती है।

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

Comments

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

— रॉस पैटरसन

Answer 3

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

Comments

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

— user6123723

Answer 4

अलग-अलग लोग अलग-अलग तरीकों से बेहतर सीखते हैं। कुछ लोग आपके जैसे हैं और उदाहरणों से बेहतर सीखते हैं। कुछ लोग मेरे जैसे हैं और विस्तृत प्रलेखन से बेहतर सीखते हैं। प्रलेखन में दोनों होने से लगता है कि अधिकांश डेवलपर्स बहुत अच्छी तरह से कवर करते हैं। एक शिक्षक से बात करें, वे आपको आधा दर्जन तरीके बता सकते हैं जो लोग सीखते हैं।