अच्छे कोड में इसे समझने में सहायता के लिए टिप्पणियाँ शामिल होती हैं, और डॉकस्ट्रिंग्स इसमें प्रमुख भूमिका निभा सकते हैं।
उचित प्रलेखन के बिना, आपके कोड को समझना, बनाए रखना और डीबग करना कठिन हो सकता है। पायथन में, आप संक्षिप्त विवरण और कोड कैसे काम करते हैं, इसके उदाहरण प्रदान करने के लिए डॉकस्ट्रिंग्स का उपयोग कर सकते हैं।
डॉकस्ट्रिंग्स क्या हैं?
डॉकस्ट्रिंग्स वे तार हैं जिन्हें आप अपने पायथन कोड में जोड़ सकते हैं यह समझाने के लिए कि यह क्या करता है और इसका उपयोग कैसे करना है। कोड का टुकड़ा एक हो सकता है पायथन समारोह, एक मॉड्यूल, या एक वर्ग।
डॉकस्ट्रिंग्स काफी हद तक मानक पायथन टिप्पणियों की तरह दिखती हैं, लेकिन उनमें कुछ अंतर हैं। पायथन टिप्पणियाँ डेवलपर्स को कोड की आंतरिक कार्यप्रणाली के बारे में अतिरिक्त जानकारी प्रदान करती हैं, जैसे कोड का विस्तार करते समय कार्यान्वयन विवरण या चेतावनियां ध्यान में रखना।
दूसरी ओर, डॉकस्ट्रिंग्स ज्यादातर कोड के उपयोगकर्ताओं को जानकारी प्रदान करते हैं, जिन्हें इसके कार्यान्वयन के विवरण को जानने की आवश्यकता नहीं है, लेकिन यह समझने की आवश्यकता है कि यह क्या करता है और इसका उपयोग कैसे करना है।
डॉकस्ट्रिंग्स कैसे लिखें
आप आमतौर पर उस कोड के ब्लॉक की शुरुआत में डॉकस्ट्रिंग शामिल करते हैं जिसे आप दस्तावेज़ बनाना चाहते हैं। आपको उन्हें ट्रिपल कोट्स में संलग्न करना होगा (). आप एक-पंक्ति डॉकस्ट्रिंग या बहु-पंक्ति डॉकस्ट्रिंग लिख सकते हैं।
एक-पंक्ति डॉकस्ट्रिंग सरल कोड के लिए उपयुक्त हैं जिसके लिए बहुत अधिक दस्तावेज़ीकरण की आवश्यकता नहीं होती है।
नीचे गुणा नामक फ़ंक्शन का एक उदाहरण दिया गया है। डॉकस्ट्रिंग बताता है कि गुणा फ़ंक्शन दो नंबर लेता है, उन्हें गुणा करता है और परिणाम देता है।
डीईएफ़गुणा(ए, बी):
दो संख्याओं का गुणा करता है और परिणाम लौटाता है
वापस करना ए * बी
अधिक जटिल कोड के लिए बहु-पंक्ति डॉकस्ट्रिंग का उपयोग करें जिसके लिए विस्तृत दस्तावेज़ीकरण की आवश्यकता होती है।
निम्नलिखित कार वर्ग पर विचार करें:
कक्षाकार:
ए कक्षाका प्रतिनिधित्वएकारवस्तु.गुण:
माइलेज (फ्लोट): कार का वर्तमान माइलेज।तरीके:
चलाना (मील): कार चलाता है के लिए मील की निर्दिष्ट संख्या।डीईएफ़__इस में__(सेल्फ, माइलेज):
सेल्फ.माइलेज = माइलेजडीईएफ़गाड़ी चलाना(स्वयं, मील):
गाड़ी चलाता है के लिए मील की निर्दिष्ट संख्या।आर्ग्स:
मील (फ्लोट): ड्राइव करने के लिए मील की संख्या।
रिटर्न:
कोई नहीं
सेल्फ.माइलेज += मील
उपरोक्त वर्ग के लिए डॉकस्ट्रिंग वर्णन करता है कि वर्ग क्या दर्शाता है, इसकी विशेषताएँ और इसकी विधियाँ। इस बीच, ड्राइव विधि के लिए डॉकस्ट्रिंग यह जानकारी प्रदान करता है कि विधि क्या करती है, इसके द्वारा अपेक्षित तर्क और यह क्या लौटाता है।
इससे इस वर्ग के साथ काम करने वाले किसी भी व्यक्ति के लिए यह समझना आसान हो जाता है कि इसका उपयोग कैसे किया जाए। डॉकस्ट्रिंग का उपयोग करने के अन्य लाभों में शामिल हैं:
- कोड मेंटेनेंस: कोड कैसे काम करता है, इसका स्पष्ट विवरण प्रदान करके, डॉकस्ट्रिंग्स डेवलपर्स को त्रुटियों को पेश किए बिना कोड को संशोधित और अपडेट करने में मदद करते हैं।
- आसान सहयोग: जब कई डेवलपर एक ही कोड बेस पर सहयोग कर रहे हों—उदाहरण के लिए, विजुअल स्टूडियो लाइव शेयर टूल—डॉकस्ट्रिंग्स डेवलपर्स को कोड को लगातार दस्तावेज करने की अनुमति देते हैं ताकि टीम पर हर कोई इसे समझ सके।
- बेहतर कोड पठनीयता: डॉकस्ट्रिंग्स एक उच्च-स्तरीय सारांश प्रदान करता है कि कौन सा कोड अनुमति देता है कोड को पढ़ने वाला कोई भी व्यक्ति पूरे कोड को पढ़े बिना इसके उद्देश्य को जल्दी से समझ सकता है अवरोध पैदा करना।
डॉकस्ट्रिंग प्रारूप
एक अच्छे डॉकस्ट्रिंग को यह वर्णन करना चाहिए कि कोड का एक टुकड़ा क्या करता है, इसके द्वारा अपेक्षित तर्क, और यदि आवश्यक हो तो कार्यान्वयन विवरण। इसमें विशेष रूप से किसी भी किनारे के मामलों को शामिल किया जाना चाहिए, जो कोड का उपयोग करने वाले किसी भी व्यक्ति के बारे में पता होना चाहिए।
एक बुनियादी डॉकस्ट्रिंग प्रारूप में निम्नलिखित खंड होते हैं:
- सारांश पंक्ति: कोड क्या करता है इसका एक-पंक्ति सारांश।
- तर्क: तर्कों के बारे में जानकारी जो फ़ंक्शन उनके डेटा प्रकारों सहित अपेक्षा करता है।
- रिटर्न वैल्यू: फ़ंक्शन के रिटर्न वैल्यू के बारे में जानकारी, इसके डेटा प्रकार सहित।
- उठाता है (वैकल्पिक): फ़ंक्शन द्वारा उठाए जा सकने वाले किसी भी अपवाद के बारे में जानकारी।
यह केवल एक मूल प्रारूप है क्योंकि ऐसे अन्य प्रारूप हैं जिन्हें आप अपने डॉकस्ट्रिंग्स को आधार बनाने के लिए चुन सकते हैं। सबसे लोकप्रिय हैं एपीटेक्स्ट, रीस्ट्रक्चर्डटेक्स्ट (जिसे रेस्ट के नाम से भी जाना जाता है), न्यूमपी और गूगल डॉकस्ट्रिंग्स। इनमें से प्रत्येक प्रारूप का अपना सिंटैक्स है जैसा कि निम्नलिखित उदाहरणों में दिखाया गया है:
एपिटेक्स्ट
एक डॉकस्ट्रिंग जो एपिटेक्स्ट प्रारूप का अनुसरण करता है:
डीईएफ़गुणा(ए, बी):
दो संख्याओं का आपस में गुणा करें।
@पारम ए: गुणा करने के लिए पहला नंबर।
@ टाइप ए: इंट
@ अपरम बी: गुणा करने के लिए दूसरा नंबर।
@ टाइप बी: इंट
@return: दो संख्याओं का गुणनफल।
@rtype: इंट
वापस करना ए * बी
पुनर्गठित पाठ (आरईएसटी)
एक डॉकस्ट्रिंग जो reST प्रारूप का अनुसरण करता है:
डीईएफ़गुणा(ए, बी):
दो संख्याओं का आपस में गुणा करें।
: परम ए: गुणा करने वाली पहली संख्या।
: टाइप ए: इंट
: परम बी: गुणा करने के लिए दूसरी संख्या।
: टाइप बी: इंट
:वापस करना: दो संख्याओं का गुणनफल।
: आर टाइप: इंट
वापस करना ए * बी
Numpy
एक डॉकस्ट्रिंग जो NumPy प्रारूप का अनुसरण करता है:
डीईएफ़गुणा(ए, बी):
दो संख्याओं का आपस में गुणा करें।पैरामीटर
ए: इंट
गुणा करने वाली पहली संख्या।
बी: इंट
गुणा करने के लिए दूसरी संख्या।
रिटर्न
int यहाँ
दो संख्याओं का गुणनफल।
वापस करना ए * बी
गूगल
एक डॉकस्ट्रिंग जो Google प्रारूप का अनुसरण करता है:
डीईएफ़गुणा(ए, बी):
दो संख्याओं का आपस में गुणा करें।आर्ग्स:
a (int): गुणा करने वाली पहली संख्या।
b (int): गुणा करने के लिए दूसरी संख्या।
रिटर्न:
int: दो संख्याओं का गुणनफल।
वापस करना ए * बी
यद्यपि सभी चार डॉकस्ट्रिंग प्रारूप गुणा कार्य के लिए उपयोगी दस्तावेज प्रदान करते हैं, लेकिन NumPy और Google प्रारूपों को एपीटेक्स्ट और रेस्ट प्रारूपों की तुलना में पढ़ना आसान है।
डॉकस्ट्रिंग्स में टेस्ट कैसे शामिल करें
आप doctest मॉड्यूल का उपयोग करके अपने डॉकस्ट्रिंग में परीक्षण उदाहरण शामिल कर सकते हैं। doctest मॉड्यूल टेक्स्ट के लिए डॉकस्ट्रिंग की खोज करता है जो इंटरैक्टिव पायथन सत्रों की तरह दिखता है और फिर उन्हें यह सत्यापित करने के लिए निष्पादित करता है कि वे काम करते हैं जैसे उन्हें करना चाहिए।
डॉकटेस्ट का उपयोग करने के लिए, डॉकस्ट्रिंग में नमूना इनपुट और अपेक्षित आउटपुट शामिल करें। आप यह कैसे करेंगे इसका एक उदाहरण नीचे दिया गया है:
डीईएफ़गुणा(ए, बी):
दो संख्याओं का आपस में गुणा करें।पैरामीटर
ए: इंट
गुणा करने वाली पहली संख्या।
बी: इंट
गुणा करने के लिए दूसरी संख्या।रिटर्न
int यहाँ
दो संख्याओं का गुणनफल।
उदाहरण
>>> गुणा करें (2, 3)
6
>>> गुणा करें (0, 10)
0
>>> गुणा करें (-1, 5)
-5
वापस करना ए * बी
उदाहरण अनुभाग में विभिन्न तर्कों के साथ तीन फ़ंक्शन कॉल हैं और प्रत्येक के लिए अपेक्षित आउटपुट निर्दिष्ट करता है। जब आप नीचे दिखाए अनुसार doctest मॉड्यूल चलाते हैं, तो यह उदाहरणों को निष्पादित करेगा और वास्तविक आउटपुट की अपेक्षित आउटपुट से तुलना करेगा।
पायथन -एम doctestmultiply.py
यदि कोई मतभेद हैं, तो doctest मॉड्यूल उन्हें विफलताओं के रूप में रिपोर्ट करता है। इस तरह के डॉकस्ट्रिंग के साथ डॉकटेस्ट का उपयोग करने से आपको यह सत्यापित करने में मदद मिलती है कि कोड अपेक्षित रूप से काम कर रहा है। ध्यान दें कि doctest अधिक व्यापक के लिए प्रतिस्थापन नहीं है आपके पायथन कोड के लिए इकाई परीक्षण और एकीकरण परीक्षण.
डॉकस्ट्रिंग्स से दस्तावेज़ीकरण कैसे उत्पन्न करें
आपने अपने पायथन कोड का दस्तावेजीकरण करने के लिए डॉकस्ट्रिंग का उपयोग करने की मूल बातें और उच्च गुणवत्ता वाले दस्तावेज़ीकरण के महत्व को सीखा है। इसे एक पायदान ऊपर ले जाने के लिए, आप अपने मॉड्यूल और कार्यों के लिए उनके संबंधित डॉकस्ट्रिंग से दस्तावेज़ तैयार करना चाह सकते हैं।
स्फिंक्स सबसे लोकप्रिय प्रलेखन जनरेटर में से एक है जिसका आप उपयोग कर सकते हैं। यह डिफ़ॉल्ट रूप से रीस्ट डॉकस्ट्रिंग प्रारूप का समर्थन करता है लेकिन आप इसे Google या NumPy प्रारूप के साथ काम करने के लिए कॉन्फ़िगर कर सकते हैं।
