दस्तऐवजीकरण, README आणि कोड टिप्पण्या

नफा:

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

सॉफ्टवेअरचा सर्वात वारंवार दुर्लक्षित परंतु दीर्घकाळ टिकणारा भाग म्हणजे दस्तऐवजीकरण. कोड महिन्यानंतरही वाचनीय आहे; ज्याने ते लिहिलं ते गेले, संदर्भ विसरला आणि जे लिहिले तेच उरले. एक चांगला README (प्रोजेक्ट काय आहे आणि तो कसा स्थापित करायचा आणि कसा चालवायचा हे स्पष्ट करणारा परिचयात्मक दस्तऐवज), स्पष्टीकरणात्मक कोड टिप्पण्या आणि अद्ययावत API दस्तऐवज (इंटरफेस कसा वापरायचा हे स्पष्ट करणारा संदर्भ) टीमचा वेग थेट ठरवतो. AI दस्तऐवजीकरणातून भरपूर “लेखन थकवा” घेते — परंतु ते एका सापळ्यासह येते: AI ते काय करते ते कोडवरून अनुमान काढू शकते, परंतु असे का केले जाते हे अनेकदा कळू शकत नाही.

या युनिटमध्ये, तुम्ही README, कोड कॉमेंट, डॉकस्ट्रिंग (प्रति फंक्शन/वर्ग लिहीलेले कॉमेंट ब्लॉक), एपीआय डॉक्युमेंट आणि एआय सह चेंजलॉग कसे तयार करायचे ते शिकाल; आणि दस्तऐवजीकरणाचा सर्वात मौल्यवान भाग मानवी रीतीने कसा जपायचा: "का."

"काय" आणि "का" मधील फरक

दस्तऐवजीकरणाचे दोन स्तर आहेत. पहिले म्हणजे काय/कसे: "हे फंक्शन सूची क्रमवारी लावते", "हा आदेश स्थापित करण्यासाठी चालवा". हे कोड आणि स्ट्रक्चरमधून काढले जाऊ शकतात; AI येथे उत्कृष्ट आहे. दुसरे म्हणजे, का: "आम्ही ही सेवा सिंक्रोनस ऐवजी असिंक्रोनस का केली", "ही मर्यादा मूल्य 30 सेकंद का आहे", "आम्ही ही लायब्ररी इतरांपेक्षा का निवडली". हे कोडमध्ये लिहिलेले नाहीत; हे डिझाइन निर्णय, मर्यादा आणि भूतकाळातील वेदना यांचे उत्पादन आहे.

AI ला "का" माहित नाही; सर्वात चांगले, ते वाजवी अंदाज लावते - जे धोकादायक आहे, कारण चुकीचे कारण कोणत्याही कारणापेक्षा वाईट आहे. त्यामुळे श्रम विभागणी स्पष्ट आहे: AI मसुदा तयार करतो "काय/कसे," तुम्ही "का" जोडता. सर्वात मौल्यवान टिप्पणी म्हणजे कोड जे सांगू शकत नाही ते सांगते.

टीप: कोड स्वतः स्पष्टपणे काय म्हणतो त्यावर टिप्पणीसह पुनरावृत्ती करू नका (जसे i = i + 1 // i वाढवा). एआय कधीकधी अशा निरर्थक टिप्पण्या तयार करते; त्यांना काढून टाका आणि "का" टिप्पण्यांसाठी तुमची उर्जा समर्पित करा.

स्टेप बाय स्टेप: AI सह डॉक्युमेंटेशन जनरेशन

1. लक्ष्यित प्रेक्षक निर्दिष्ट करा. “एक विकसक नुकताच प्रारंभ करत आहे,” “बाह्य संघ जो हे API वापरेल,” “भविष्यातील मी” — प्रेक्षक भाषा आणि खोलीसाठी टोन सेट करतात.
2. स्त्रोत द्या. प्रॉम्प्टवर संबंधित कोड, विद्यमान README, उदाहरण वापर जोडा. स्रोत नसलेले दस्तऐवज हे बनावटीचे आमंत्रण आहे.
3. लादण्याची रचना. README साठी मानक विभाग (उद्देश, स्थापना, वापर, कॉन्फिगरेशन, योगदान), डॉकस्ट्रिंगसाठी प्रकल्प स्वरूप.
4. "का" स्पेस चिन्हांकित करा. AI ला ते निर्णय चिन्हांकित करण्यास सांगा ज्यासाठी त्याला "येथे 'का' नोट आवश्यक आहे" म्हणून तर्क माहित नाही; मग तुम्ही त्या रिकाम्या जागा भरा.
5. सत्यापित करा. प्रत्यक्षात स्थापना चरण चालवा; नमुना कोड वापरून पहा. एक README जो काम करत नाही तो README पेक्षा वाईट आहे.

तीन मिनी केसेस

केस 1 — README ने ऑनबोर्डिंगला गती दिली. मुक्त स्रोत साधनाचे README गहाळ होते; नवीन योगदानकर्त्यांना सरासरी 2 तास इंस्टॉलेशनसह संघर्ष करावा लागला. टीमने AI ला इन्स्टॉलेशन स्क्रिप्ट्स आणि package.json दिले आणि संरचित README चा मसुदा तयार केला, नंतर स्वच्छ मशीनवर पायऱ्या स्वतः चालवल्या आणि दोन गहाळ अवलंबित्व जोडले. त्यानंतरच्या योगदानकर्त्यांसाठी स्थापना वेळ सरासरी 25 मिनिटांपर्यंत कमी झाला.

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

केस 3 - डॉकस्ट्रिंग मानक स्वयंचलित झाले आहे. 40 फंक्शन्ससह सहाय्यक मॉड्यूलमध्ये कोणतेही डॉकस्ट्रिंग नव्हते. AI ला प्रोजेक्ट फॉरमॅट (Google स्टाईल) दिले गेले आणि प्रत्येक फंक्शनसाठी पॅरामीटर, रिटर्न आणि अपवाद वर्णन तयार केले; विकासकाने याचे पुनरावलोकन केले आणि काही चुकीच्या प्रकारच्या घोषणांचे निराकरण केले. 40 फंक्शन्सचे दस्तऐवजीकरण अर्ध्या दिवसापासून एक तासापर्यंत खाली गेले.

चार कॉपी करण्यायोग्य टेम्पलेट्स

संरचित README मसुदा:

लक्ष्य प्रेक्षक: {{उदा. new contributor}}.खालील फाइल्सवर आधारित README मसुदा लिहा. विभाग: उद्देश, वैशिष्ट्ये, आवश्यकता, स्थापना, ऑपरेशन, कॉन्फिगरेशन, चाचणी, योगदान. वास्तविक फायलींमधून इंस्टॉलेशन/रनिंग कमांड काढा; फिटिंग. तुम्हाला खात्री नसलेली ठिकाणे "[सत्यापित]" ने चिन्हांकित करा. स्रोत: {{package.json/scripts/sample code}}

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

{{project style: Google/NumPy/JSDoc}} फॉरमॅटमध्ये या फंक्शन्सवर डॉकस्ट्रिंग लिहा: लहान सारांश, पॅरामीटर्स (प्रकार + अर्थ), रिटर्न, टाकलेले अपवाद, 1 लहान उदाहरण. कोड स्पष्टपणे काय म्हणतो त्याची पुनरावृत्ती करू नका. डिझाइन निर्णय ज्यांना "का" आवश्यक आहे ते "[का आवश्यक]" म्हणून चिन्हांकित करू नका, बनावट औचित्य लिहू नका.{{code}}

"का" टिप्पणीसाठी जागा काढा:

या कोडमध्ये, पुढील विकासक "हे असे का आहे?" (जादूची संख्या, असामान्य निर्णय, वर्कअराउंड). प्रत्येकासाठी एक टिप्पणी द्या SKELETON, परंतु तर्क रिकामा सोडा; मी औचित्य भरेन.{{code}}

चेंजलॉग/पीआर विधान:

खालील फरकातून {{changelog entry / PR description}} लिहा. स्वरूप: काय बदलले (वापरकर्त्याच्या भाषेत), का (समस्या: {{...}}), ब्रेकिंग बदल (असल्यास), त्याची चाचणी केली गेली आहे का. लक्ष्यित प्रेक्षकांसाठी तांत्रिक शब्दरचना समायोजित करा.{{diff}}

कमकुवत प्रॉम्प्ट / मजबूत प्रॉम्प्ट

कमकुवत: "या प्रकल्पासाठी एक README लिहा."

सशक्त: "लक्ष्य प्रेक्षक: एक विकसक प्रथमच या रेपोचे क्लोनिंग करत आहे. संलग्न पॅकेज.json, docker-compose.yml आणि स्क्रिप्ट्स/ फोल्डरच्या आधारावर, उद्देश, आवश्यकता, स्थापना, ऑपरेशन, चाचणी, योगदान विभागांसह README मसुदा लिहा. या फायलींमधून कमांड्स काढा, जिथे तुम्हाला चिन्हांकित केले जात नाही; [सत्यापित करा]."

सशक्त आवृत्ती प्रेक्षक, स्त्रोत, रचना आणि “ते बनवा, चिन्हांकित करा” नियम देते; जेणेकरून दस्तऐवज वास्तविक फायलींवर आधारित आहे आणि सत्यापित करावयाची ठिकाणे स्पष्टपणे दृश्यमान आहेत.

दस्तऐवज प्रकार

एआय चांगले करते

मानव जोडतो/ पडताळतो

README स्थापना

चरण बाह्यरेखा

पायऱ्या चालवा आणि पुष्टी करा

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

रचना, पॅरामीटर, प्रकार

योग्य प्रकार आणि "का"

कोड टिप्पणी

"तो काय करत आहे" सारांश

"हे का" औचित्य

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

पहिला मसुदा

प्रभाव आणि अचूकता

आर्किटेक्चरल निर्णय (ADR)

सांगाडा

वास्तविक निर्णय आणि तडजोड

दस्तऐवजीकरण देखभाल आवश्यक आहे

दस्तऐवजाची सर्वात धोकादायक बाब म्हणजे जेव्हा ते खोटे असले तरीही ते खरे दिसते. जेव्हा कोड बदलतो आणि दस्तऐवज अद्यतनित केला जात नाही, तेव्हा ते सक्रियपणे वाचकांची दिशाभूल करते. AI अपडेट करणे सोपे करते: एक फरक जारी करा आणि विचारा "या बदलाचा दस्तऐवजाच्या कोणत्या भागांवर परिणाम होतो?" तुम्ही विचारू शकता. परंतु ही अशी प्रक्रिया आहे जी अद्ययावततेची खात्री देते — दस्तऐवजीकरण अपडेटला कोड बदलाचा भाग बनवा (PR च्या स्वीकृती निकष). एआय वेग वाढवते; संघ शिस्त निर्माण करतो.

खबरदारी: README मध्ये इंस्टॉलेशन चरणांची पडताळणी केल्याशिवाय प्रकाशित करू नका. "कदाचित कार्य" दस्तऐवज नवीन विकसकाचा पहिला दिवस खराब करू शकतो आणि विश्वास नष्ट करू शकतो. स्वच्छ वातावरणात पायऱ्या स्वतः चालवा.

सामान्य चुका

• AI मध्ये बसण्यासाठी “का” मिळवणे. चुकीचे औचित्य हे औचित्य नसण्यापेक्षा वाईट आहे; कोड मालकाने डिझाइनचे कारण लिहावे.
• स्थापना चरणांची पडताळणी करत नाही. README जे काम करत नाही ते विश्वास नष्ट करते.
• कोडची पुनरावृत्ती करणारी अनावश्यक टिप्पणी. ते आवाज निर्माण करते, वास्तविक "का" व्याख्या अस्पष्ट करते.
• लक्ष्यित प्रेक्षक निर्दिष्ट करत नाही. ते कोणासाठी लिहिलेले आहे हे स्पष्ट नसलेले दस्तऐवज नवशिक्या किंवा तज्ञांना काहीही उपयोगाचे नाही.
• प्रक्रियेपासून अपडेट वेगळे करत आहे. दस्तऐवज कोडसह अद्यतनित न केल्यास ते त्वरीत दिशाभूल करणारे बनते.

सारांशात

AI दस्तऐवजातून बराच यांत्रिक ओझे घेते: द्रुत मसुदे README, docstring, API संदर्भ, चेंजलॉग आणि PR वर्णन. परंतु ते "का" जाणू शकत नाही, जो सर्वात मौल्यवान थर आहे आणि तो तयार करणे धोकादायक आहे. श्रम विभागणी स्पष्ट आहे: AI "काय/कसे" तयार करते, तुम्ही "का" जोडता. प्रेक्षक निर्दिष्ट करा, संसाधने प्रदान करा, रचना लागू करा, बसण्यासाठी ठिकाणे चिन्हांकित करा आणि प्रत्येक स्थापना चरण स्वतः चालवून सत्यापित करा. दस्तऐवजीकरण हा कोड बदलाचा अविभाज्य भाग बनवा.

अर्ज कार्य

एक मॉड्यूल किंवा लहान प्रकल्प निवडा ज्याचे दस्तऐवजीकरण गहाळ किंवा जुने आहे. प्रथम “संरचित README मसुदा” (किंवा डॉकस्ट्रिंग) टेम्पलेटसह AI मधून बाह्यरेखा तयार करा; स्त्रोत आणि लक्ष्यित प्रेक्षक देण्याची खात्री करा. त्यानंतर AI ने चिन्हांकित केलेल्या प्रत्येक बिंदूवर जा [पडताळणी] किंवा [का आवश्यक आहे]: प्रत्यक्षात सेटअप पायऱ्या चालवा आणि तुमच्या स्वतःच्या ज्ञानाने "का" डिझाइन भरा. किती पायऱ्या निश्चित करणे आवश्यक आहे आणि तुम्ही किती "का" जोडले ते लक्षात ठेवा.

चेकलिस्ट

• [ ] दस्तऐवजीकरणात, मी "काय/कसे" आणि "का" स्तर वेगळे करतो.
• [ ] मी AI ला "का" बनवत नाही, मी ते स्वतः जोडतो.
• [ ] मी प्रॉम्प्टला लक्ष्यित प्रेक्षक आणि वास्तविक स्त्रोत फाइल्स देतो.
• [ ] मी AI ने चिन्हांकित केलेले [सत्यापित] गुण वैयक्तिकरित्या कार्यान्वित करून सत्यापित करतो.
• [ ] मी कोडची पुनरावृत्ती करणाऱ्या अनावश्यक टिप्पण्या काढून टाकतो.
• [ ] मी दस्तऐवजीकरण अद्यतन हा कोड बदलाचा भाग बनवत आहे.