दस्तावेज़ीकरण, रीडमी और कोड टिप्पणियाँ

लाभ:

• AI के साथ लक्षित दर्शकों और स्रोत के आधार पर README, डॉकस्ट्रिंग और चेंजलॉग ड्राफ्ट तैयार करने की क्षमता
• दस्तावेज़ीकरण में 'क्या/कैसे' और 'क्यों' परतों को अलग करने और एक मानव के रूप में 'क्यों' जोड़ने की क्षमता
• इंस्टॉलेशन चरणों को व्यक्तिगत रूप से चलाकर और दस्तावेज़ को कोड परिवर्तन का हिस्सा बनाकर सत्यापित करना

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

इस इकाई में, आप सीखेंगे कि रीडमी, कोड टिप्पणी, डॉकस्ट्रिंग (प्रति फ़ंक्शन/कक्षा में लिखी गई टिप्पणी ब्लॉक), एपीआई दस्तावेज़ और एआई के साथ चेंजलॉग कैसे तैयार करें; और दस्तावेज़ीकरण के सबसे मूल्यवान हिस्से को मानवीय रूप से कैसे संरक्षित किया जाए: "क्यों।"

"क्या" और "क्यों" के बीच अंतर

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

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

युक्ति: किसी टिप्पणी के साथ वह न दोहराएं जो कोड स्वयं स्पष्ट रूप से कहता है (जैसे i = i + 1 // i को एक से बढ़ाएं)। एआई कभी-कभी ऐसी अनावश्यक टिप्पणियाँ उत्पन्न करता है; उन्हें हटा दें और अपनी ऊर्जा "क्यों" टिप्पणियों पर लगाएं।

चरण दर चरण: एआई के साथ दस्तावेज़ीकरण निर्माण

1. लक्षित दर्शक निर्दिष्ट करें. "एक डेवलपर जो अभी शुरुआत कर रहा है," "बाहरी टीम जो इस एपीआई का उपयोग करेगी," "भविष्य का मैं" - दर्शक भाषा और गहराई के लिए स्वर निर्धारित करते हैं।
2. स्रोत बतायें. प्रॉम्प्ट में प्रासंगिक कोड, मौजूदा README, उदाहरण उपयोग जोड़ें। एक बिना स्रोत वाला दस्तावेज़ निर्माण का निमंत्रण है।
3. अधिरोपण संरचना. README के ​​लिए मानक अनुभाग (उद्देश्य, स्थापना, उपयोग, कॉन्फ़िगरेशन, योगदान), डॉकस्ट्रिंग के लिए प्रोजेक्ट प्रारूप।
4. "क्यों" रिक्त स्थान को चिह्नित करें। एआई से उन निर्णयों को चिह्नित करने के लिए कहें जिनके लिए उसे तर्क नहीं पता है "यहां 'क्यों' नोट की आवश्यकता है" के रूप में; फिर आप उन रिक्त स्थानों को भरें.
5. सत्यापित करें। वास्तव में संस्थापन चरण चलाएँ; नमूना कोड आज़माएँ. एक README जो काम नहीं करता वह बिल्कुल भी README न होने से भी बदतर है।

तीन मिनी मामले

केस 1 - रीडमी त्वरित ऑनबोर्डिंग। एक ओपन सोर्स टूल का README गायब था; नए योगदानकर्ताओं को औसतन 2 घंटे तक इंस्टालेशन में संघर्ष करना पड़ा। टीम ने एआई को इंस्टॉलेशन स्क्रिप्ट और पैकेज.जेसन दिया और एक संरचित रीडमी का मसौदा तैयार किया, फिर एक साफ मशीन पर चरणों को स्वयं चलाया और दो लापता निर्भरताएं जोड़ दीं। बाद के योगदानकर्ताओं के लिए इंस्टॉलेशन का समय घटकर औसतन 25 मिनट हो गया।

केस 2 - बना-बनाया "क्यों" जाल। एक डेवलपर ने एआई से टाइमआउट मान (टाइमआउट=30) के आगे एक टिप्पणी मांगी। एआई ने "उच्च नेटवर्क विलंबता को सहन करने के लिए" एक उचित लेकिन गलत औचित्य लिखा; वास्तविक कारण डाउनस्ट्रीम सेवा की संविदात्मक 30-सेकंड की सीमा थी। गलत व्याख्या के कारण बाद के डेवलपर ने अनावश्यक रूप से मूल्य बढ़ाया, जिससे एक घटना हुई। पाठ: कोड स्वामी को औचित्य सत्यापित करना होगा।

केस 3 - डॉकस्ट्रिंग मानक स्वचालित हो गया है। 40 फ़ंक्शंस वाले एक सहायक मॉड्यूल में कोई डॉकस्ट्रिंग नहीं थी। एआई को प्रोजेक्ट प्रारूप (Google शैली) दिया गया और प्रत्येक फ़ंक्शन के लिए पैरामीटर, रिटर्न और अपवाद विवरण तैयार किए गए; डेवलपर ने इनकी समीक्षा की और कुछ गलत प्रकार की घोषणाओं को ठीक किया। 40 कार्यों का दस्तावेजीकरण करने में लगभग आधे दिन से लेकर एक घंटे तक का समय लग गया।

चार प्रतिलिपि योग्य टेम्पलेट

संरचित रीडमी ड्राफ्ट:

लक्षित दर्शक: {{उदा. नया योगदानकर्ता}}। नीचे दी गई फ़ाइलों के आधार पर एक ड्राफ्ट README लिखें। अनुभाग: उद्देश्य, सुविधाएँ, आवश्यकताएँ, स्थापना, संचालन, विन्यास, परीक्षण, योगदान। वास्तविक फ़ाइलों से इंस्टॉलेशन/रनिंग कमांड निकालें; फिटिंग. जिन स्थानों के बारे में आप निश्चित नहीं हैं उन्हें "[सत्यापित करें]" से चिह्नित करें। स्रोत: {{package.json/स्क्रिप्ट/नमूना कोड}}

डॉकस्ट्रिंग/एपीआई संदर्भ:

इन फ़ंक्शनों के लिए डॉकस्ट्रिंग को {{प्रोजेक्ट शैली: Google/NumPy/JSDoc}} प्रारूप में लिखें: संक्षिप्त सारांश, पैरामीटर (प्रकार + अर्थ), वापसी, अपवाद फेंके गए, 1 संक्षिप्त उदाहरण। कोड जो स्पष्ट रूप से कहता है उसे दोबारा न दोहराएं। ऐसे डिज़ाइन निर्णय जिनमें "क्यों" की आवश्यकता होती है उन्हें "[क्यों आवश्यक]" के रूप में चिह्नित करें, कोई मनगढ़ंत औचित्य न लिखें।

"क्यों" टिप्पणी के लिए रिक्त स्थान हटाएँ:

इस कोड में, अगला डेवलपर पूछ सकता है "ऐसा क्यों है?" (जादुई संख्याएँ, असामान्य निर्णय, समाधान)। प्रत्येक के लिए एक टिप्पणी SKELETON दें, लेकिन तर्क को खाली छोड़ दें; मैं औचित्य भर दूंगा.{{कोड}}

चेंजलॉग/पीआर स्टेटमेंट:

नीचे दिए गए अंतर से एक {{चेंजलॉग प्रविष्टि / पीआर विवरण}} लिखें। प्रारूप: क्या बदला (उपयोगकर्ता की भाषा में), क्यों (मुद्दा: {{...}}), ब्रेकिंग परिवर्तन (यदि कोई हो), क्या इसका परीक्षण किया गया है। लक्षित दर्शकों के लिए तकनीकी शब्दजाल को समायोजित करें।

कमजोर संकेत/मजबूत संकेत

कमज़ोर: "इस प्रोजेक्ट के लिए एक README लिखें।"

मजबूत: "लक्षित दर्शक: एक डेवलपर पहली बार इस रेपो की क्लोनिंग कर रहा है। संलग्न पैकेज.जेसन, डॉकर-कंपोज.वाईएमएल और स्क्रिप्ट/फ़ोल्डर के आधार पर, उद्देश्य, आवश्यकताएं, स्थापना, संचालन, परीक्षण, योगदान अनुभागों के साथ एक ड्राफ्ट रीडमी लिखें। इन फ़ाइलों से कमांड निकालें, उन्हें न बनाएं; जहां भी आप सुनिश्चित नहीं हैं वहां [सत्यापित करें] के साथ चिह्नित करें।"

मजबूत संस्करण दर्शकों, स्रोत, संरचना और "इसे बनाएं, इसे चिह्नित करें" नियम देता है; ताकि दस्तावेज़ वास्तविक फ़ाइलों पर आधारित हो और सत्यापित किए जाने वाले स्थान स्पष्ट रूप से दिखाई दें।

दस्तावेज़ प्रकार

एआई अच्छा करता है

मानव जोड़ता/सत्यापित करता है

रीडमी इंस्टालेशन

चरण की रूपरेखा

चरण चलाएँ और पुष्टि करें

डॉकस्ट्रिंग/एपीआई

संरचना, पैरामीटर, प्रकार

सही प्रकार और "क्यों"

कोड टिप्पणी

"वह क्या कर रहा है" सारांश

"ऐसा क्यों है" औचित्य

चेंजलॉग/पीआर

पहला मसौदा

प्रभाव और सटीकता

वास्तुशिल्प निर्णय (एडीआर)

कंकाल

वास्तविक निर्णय और समझौते

दस्तावेज़ीकरण के लिए रखरखाव की आवश्यकता होती है

किसी दस्तावेज़ का सबसे खतरनाक पहलू वह होता है जब वह झूठ होते हुए भी सच प्रतीत होता है। जब कोड बदलता है और दस्तावेज़ अद्यतन नहीं होता है, तो यह सक्रिय रूप से पाठक को गुमराह करता है। एआई अपडेट करना आसान बनाता है: एक अंतर जारी करें और पूछें "यह परिवर्तन दस्तावेज़ के किन हिस्सों को प्रभावित करता है?" आप पूछ सकते हैं। लेकिन यह वह प्रक्रिया है जो अद्यतनता सुनिश्चित करती है - दस्तावेज़ीकरण अद्यतन को कोड परिवर्तन (पीआर की स्वीकृति मानदंड) का हिस्सा बनाएं। एआई में तेजी आती है; टीम अनुशासन बनाती है।

सावधानी: README में इंस्टॉलेशन चरणों को सत्यापित किए बिना प्रकाशित न करें। एक "संभवतः काम करने वाला" दस्तावेज़ एक नए डेवलपर का पहला दिन बर्बाद कर सकता है और विश्वास को ख़त्म कर सकता है। स्वच्छ वातावरण में सीढ़ियाँ स्वयं चलाएँ।

सामान्य गलतियाँ

• एआई में फिट होने के लिए "क्यों" प्राप्त करना। झूठा औचित्य, औचित्य न होने से भी बदतर है; कोड स्वामी को डिज़ाइन कारण लिखना चाहिए.
• स्थापना चरणों का सत्यापन नहीं किया जा रहा है. जो README काम नहीं करता वह विश्वास को नष्ट कर देता है।
• कोड को दोहराते हुए अनावश्यक टिप्पणी। यह शोर पैदा करता है, वास्तविक "क्यों" व्याख्याओं को अस्पष्ट करता है।
• लक्षित दर्शकों को निर्दिष्ट नहीं करना. जो दस्तावेज़ यह स्पष्ट नहीं है कि यह किसके लिए लिखा गया है, वह नौसिखिए या विशेषज्ञ के लिए किसी काम का नहीं है।
• अद्यतन को प्रक्रिया से अलग करना. यदि दस्तावेज़ को कोड के साथ अद्यतन नहीं किया गया है तो यह शीघ्र ही भ्रामक हो जाता है।

संक्षेप में

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

आवेदन कार्य

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

चेकलिस्ट

• [ ] दस्तावेज़ीकरण में, मैं "क्या/कैसे" और "क्यों" परतों को अलग करता हूं।
• [ ] मैं एआई को "क्यों" नहीं बनाता, मैं इसे स्वयं जोड़ता हूं।
• [ ] मैं लक्षित दर्शकों और वास्तविक स्रोत फ़ाइलों को संकेत देता हूं।
• [ ] मैं एआई द्वारा चिह्नित [सत्यापित] बिंदुओं को व्यक्तिगत रूप से निष्पादित करके सत्यापित करता हूं।
• [ ] मैं कोड को दोहराने वाली अनावश्यक टिप्पणियों को हटा देता हूं।
• [ ] मैं दस्तावेज़ीकरण अद्यतन को कोड परिवर्तन का हिस्सा बना रहा हूं।