ලේඛනගත කිරීම, README සහ කේත අදහස්

ලාභ:

• AI සමඟ ඉලක්කගත ප්‍රේක්ෂකයින් සහ මූලාශ්‍රය මත පදනම්ව README, docstring සහ changelog කෙටුම්පත් නිෂ්පාදනය කිරීමේ හැකියාව
• ලේඛනගත කිරීමේදී 'කුමක්ද/කොහොමද' සහ 'ඇයි' ස්ථර වෙන්කර 'ඇයි' මනුෂ්‍යයෙකු ලෙස එක් කිරීමට හැකියාව
• ස්ථාපන පියවර පුද්ගලිකව ධාවනය කිරීමෙන් සහ ලේඛනය කේත වෙනස් කිරීමේ කොටසක් බවට පත් කිරීමෙන් තහවුරු කිරීම

බොහෝ විට නොසලකා හරින ලද නමුත් මෘදුකාංගයේ දීර්ඝතම කොටස වන්නේ ලේඛනගත කිරීමයි. කේතය මාස කිහිපයකට පසුව පවා කියවිය හැකිය; ඒක ලියපු කෙනා නැතිවෙලා, සන්දර්භය අමතක වෙලා, ලියපු දේ විතරක් ඉතුරු වෙනවා. හොඳ README (ව්‍යාපෘතියක් යනු කුමක්ද සහ එය ස්ථාපනය කර ක්‍රියාත්මක කරන්නේ කෙසේද යන්න පැහැදිලි කරන හඳුන්වාදීමේ ලේඛනයක්), පැහැදිලි කිරීමේ කේත අදහස් සහ යාවත්කාලීන API ප්‍රලේඛනයක් (අතුරු මුහුණතක් භාවිතා කරන ආකාරය පැහැදිලි කරන යොමුවක්) කණ්ඩායමක වේගය කෙලින්ම තීරණය කරයි. AI විසින් ලියකියවිලි වලින් "ලිවීමේ තෙහෙට්ටුව" බොහොමයක් ඉවත් කරයි - නමුත් එය උගුලක් සමඟ පැමිණේ: AI හට එය කරන්නේ කුමක්දැයි කේතයෙන් අනුමාන කළ හැකිය, නමුත් එය එසේ කරන්නේ මන්දැයි බොහෝ විට දැනගත නොහැක.

මෙම ඒකකය තුළ, ඔබ README නිෂ්පාදනය කරන ආකාරය, කේත අදහස් දැක්වීම, docstring (ක්‍රියාකාරීත්වය/පන්තියකට ලියන ලද අදහස් වාරණ), API ලේඛනය සහ AI සමඟ වෙනස් කිරීම ඉගෙන ගනු ඇත; සහ ලියකියවිලි වල වටිනාම කොටස මානුෂීය ලෙස සංරක්ෂණය කරන්නේ කෙසේද: "ඇයි."

"කුමක්ද" සහ "ඇයි" අතර වෙනස

ලේඛන ස්ථර දෙකක් ඇත. පළමුවැන්න කුමක්ද/කෙසේද: "මෙම ශ්‍රිතය ලැයිස්තුවක් වර්ග කරයි", "ස්ථාපනය කිරීමට මෙම විධානය ක්‍රියාත්මක කරන්න". මේවා කේතයෙන් සහ ව්‍යුහයෙන් උපුටා ගත හැක; AI මෙහි විශිෂ්ටයි. දෙවනුව, ඇයි: "අපි මෙම සේවාව සමමුහුර්ත කිරීමට වඩා අසමමුහුර්ත කළේ ඇයි", "මෙම සීමාව තත්පර 30 ක් වන්නේ ඇයි", "අපි මෙම පුස්තකාලය අනෙකට වඩා තෝරා ගත්තේ ඇයි". මේවා කේතයේ ලියා නැත; එය සැලසුම් තීරණ, සීමා කිරීම් සහ අතීත වේදනාවන්ගේ නිෂ්පාදනයකි.

AI "ඇයි" දන්නේ නැහැ; හොඳම දෙය නම්, එය සාධාරණ අනුමානයක් සාදයි - එය භයානක ය, මන්ද වැරදි හේතුවක් කිසිඳු හේතුවක් නොමැතිව නරක ය. එබැවින් ශ්රම බෙදීම පැහැදිලිය: AI කෙටුම්පත් කරන්නේ "කුමක් / කෙසේද" යන්නයි, ඔබ "ඇයි" එකතු කරන්න. කෝඩ් එකෙන් කියන්න බැරි දේ කියන එක තමයි වටිනම කමෙන්ට් එක.

ඉඟිය: කේතයම පැහැදිලිව පවසන දේ අදහස් දැක්වීමක් සමඟ නැවත නොකරන්න (i = i + 1 // i එකකින් වැඩි කරන්න). AI සමහර විට එවැනි අතිරික්ත අදහස් ඉදිරිපත් කරයි; ඒවා ඉවත් කර "ඇයි" අදහස් දැක්වීමට ඔබේ ශක්තිය කැප කරන්න.

පියවරෙන් පියවර: AI සමඟ ලේඛන උත්පාදනය

1. ඉලක්කගත ප්රේක්ෂකයින් සඳහන් කරන්න. “දැන් ආරම්භ කරන සංවර්ධකයෙක්,” “මෙම API භාවිතා කරන බාහිර කණ්ඩායම,” “අනාගත මා” - ප්‍රේක්ෂකයින් භාෂාව සහ ගැඹුර සඳහා තානය සකසයි.
2. මූලාශ්‍රය දෙන්න. අදාළ කේතය, පවතින README, උදාහරණ භාවිතය ප්‍රේරකයට එක් කරන්න. මූලාශ්‍ර රහිත ලියවිල්ලක් යනු ප්‍රබන්ධ කිරීමට ආරාධනා කිරීමකි.
3. පැනවීමේ ව්යුහය. README සඳහා සම්මත කොටස් (අරමුණ, ස්ථාපනය, භාවිතය, වින්‍යාස කිරීම, දායකත්වය), docstring සඳහා ව්‍යාපෘති ආකෘතිය.
4. "ඇයි" හිස්තැන් සලකුණු කරන්න. තාර්කිකත්වය නොදන්නා තීරණ "මෙහි 'ඇයි' සටහනක් අවශ්‍ය වේ" ලෙස සලකුණු කරන ලෙස AI වෙතින් ඉල්ලා සිටින්න; එවිට ඔබ එම හිස් තැන් පුරවන්න.
5. තහවුරු කරන්න. ඇත්ත වශයෙන්ම ස්ථාපන පියවර ක්රියාත්මක කරන්න; නියැදි කේතය උත්සාහ කරන්න. ක්‍රියා නොකරන README එකක් README එකකට වඩා නරකයි.

කුඩා නඩු තුනක්

1 වන අවස්ථාව - README ඔන්බෝඩ් කිරීම වේගවත් කරන ලදී. විවෘත මූලාශ්‍ර මෙවලමක README අතුරුදහන් විය; නව දායකයින් සාමාන්‍යයෙන් පැය 2ක් සඳහා ස්ථාපනය සමඟ අරගල කළහ. කණ්ඩායම විසින් ස්ථාපන ස්ක්‍රිප්ට් සහ package.json AI වෙත ලබා දී ව්‍යුහගත README එකක් කෙටුම්පත් කර, පසුව පිරිසිදු යන්ත්‍රයක් මත පියවර ධාවනය කර අතුරුදහන් වූ පරායත්තතා දෙක එකතු කරන ලදී. පසුකාලීන දායකයින් සඳහා ස්ථාපන කාලය සාමාන්‍ය මිනිත්තු 25 දක්වා අඩු විය.

නඩුව 2 - සෑදූ "ඇයි" උගුල. සංවර්ධකයෙක් AI වෙතින් කල් ඉකුත්වීමේ අගයක් (කාලය ඉක්මවීම=30) අසල අදහසක් ඉල්ලා සිටියේය. AI විසින් "අධික ජාල ප්‍රමාදය ඉවසා සිටීම සඳහා" සාධාරණ නමුත් වැරදි සාධාරණීකරණයක් ලියා ඇත; සැබෑ හේතුව වූයේ පහළ සේවාවක ගිවිසුම්ගත තත්පර 30 සීමාවයි. වැරදි අර්ථකථනය පසුකාලීන සංවර්ධකයෙකුට අනවශ්‍ය ලෙස වටිනාකම වැඩි කිරීමට හේතු වූ අතර එය සිදුවීමකට තුඩු දුන්නේය. පාඩම: කේත හිමිකරු සාධාරණීකරණය තහවුරු කළ යුතුය.

3 වන අවස්ථාව - Docstring සම්මතය ස්වයංක්‍රීය වී ඇත. ශ්‍රිත 40ක් සහිත සහායක මොඩියුලයකට ලේඛන නොමැත. AI හට ව්‍යාපෘති ආකෘතිය (ගූගල් විලාසය) ලබා දී ඇති අතර එක් එක් කාර්යය සඳහා පරාමිතිය, ප්‍රතිලාභ සහ ව්‍යතිරේක විස්තර නිෂ්පාදනය කරන ලදී; සංවර්ධකයා මේවා සමාලෝචනය කර වැරදි ආකාරයේ ප්‍රකාශ කිහිපයක් සවි කර ඇත. කාර්යයන් 40ක් ලේඛනගත කිරීම දින භාගයක පමණ සිට පැයක් දක්වා අඩු විය.

පිටපත් කළ හැකි සැකිලි හතරක්

ව්‍යුහගත README කෙටුම්පත:

ඉලක්කගත ප්‍රේක්ෂකයින්: {{උදා. නව දායකයා}}.පහත ගොනු මත පදනම්ව README කෙටුම්පතක් ලියන්න. අංශ: අරමුණ, විශේෂාංග, අවශ්‍යතා, ස්ථාපනය, ක්‍රියාත්මක කිරීම, වින්‍යාස කිරීම, පරීක්ෂා කිරීම, දායකත්වය. සැබෑ ගොනු වලින් ස්ථාපන/ධාවන විධාන උපුටා ගන්න; සවි කිරීම. ඔබට විශ්වාස නැති ස්ථාන "[සත්‍යාපනය]" මගින් සලකුණු කරන්න. මූලාශ්‍රය: {{package.json / scripts / නියැදි කේතය}}

Docstring/API යොමුව:

{{ව්‍යාපෘති විලාසය: Google/NumPy/JSDoc}} ආකෘතියෙන් මෙම කාර්යයන් සඳහා docstring ලියන්න: කෙටි සාරාංශය, පරාමිති (වර්ගය + අර්ථය), ආපසු හැරීම, ව්‍යතිරේක විසි කිරීම, 1 කෙටි උදාහරණය. කේතය පැහැදිලිව කියන දේ නැවත නොකියන්න. "ඇයි" අවශ්‍ය වන නිර්මාණ තීරණ "[ඇයි අවශ්‍ය]" ලෙස සලකුණු කරන්න, ගොතන ලද සාධාරණීකරණයක් ලියන්න එපා.{{කේතය}}

"ඇයි" අදහස සඳහා හිස්තැන් ඉවත් කරන්න:

මෙම කේතය තුළ, ඊළඟ සංවර්ධකයා "මෙය එසේ වන්නේ ඇයි?" (මැජික් අංක, අසාමාන්ය තීරණ, විසඳුම්). එක් එක් සඳහා SKELETON යනුවෙන් අදහස් දක්වන්න, නමුත් තාර්කිකත්වය හිස්ව තබන්න; මම සාධාරණීකරණය පුරවන්නම්.{{code}}

Changelog/PR ප්‍රකාශය:

පහත වෙනසෙන් {{changelog entry / PR විස්තරයක්}} ලියන්න. ආකෘතිය: වෙනස් වූ දේ (පරිශීලක භාෂාවෙන්), ඇයි (නිකුතුව: {{...}}), බිඳීමේ වෙනසක් (ඇත්නම්), එය පරීක්ෂා කර තිබේද. ඉලක්කගත ප්‍රේක්ෂකයන්ට තාක්ෂණික වාක්‍ය සකසන්න.{{diff}}

දුර්වල ක්ෂණික / ශක්තිමත් විමසුම

දුර්වල: "මෙම ව්යාපෘතිය සඳහා README ලියන්න."

ප්‍රබල: "ඉලක්කගත ප්‍රේක්ෂකයින්: සංවර්ධකයෙක් මෙම රෙපෝව ප්‍රථම වරට ක්ලෝන කරයි. අමුණා ඇති package.json, docker-compose.yml සහ scripts/ ෆෝල්ඩරය මත පදනම්ව, අරමුණ, අවශ්‍යතා, ස්ථාපනය, මෙහෙයුම, පරීක්ෂා කිරීම, දායකත්ව යන කොටස් සමඟින් README කෙටුම්පතක් ලියන්න. මෙම ගොනු වලින් විධානයන් කිසි තැනක උකහා නොගන්න; [තහවුරු කරන්න]."

ප්රබල අනුවාදය ප්රේක්ෂකයන්ට, මූලාශ්රය, ව්යුහය සහ "එය සාදන්න, එය සලකුණු කරන්න" රීතිය ලබා දෙයි; ලේඛනය සැබෑ ලිපිගොනු මත පදනම් වන අතර සත්‍යාපනය කළ යුතු ස්ථාන පැහැදිලිව දැකගත හැකිය.

ලේඛන වර්ගය

AI හොඳින් කරයි

මිනිසා එකතු කරයි/සත්‍යාපනය කරයි

README ස්ථාපනය

පියවර දළ සටහන

පියවර ධාවනය කර තහවුරු කරන්න

Docstring/API

ව්යුහය, පරාමිතිය, වර්ගය

නිවැරදි වර්ගය සහ "ඇයි"

කේත අදහස් දැක්වීම

"ඔහු කරන්නේ කුමක්ද" සාරාංශය

"ඇයි මේ" සාධාරණීකරණය

චේන්ජ්ලොග්/PR

පළමු කෙටුම්පත

බලපෑම සහ නිරවද්යතාව

වාස්තු විද්‍යාත්මක තීරණය (ADR)

ඇටසැකිල්ල

සැබෑ තීරණ සහ සම්මුතීන්

ලේඛන නඩත්තුව අවශ්ය වේ

ලේඛනයක ඇති භයානකම අංගය නම් එය අසත්‍ය වුවත් එය සත්‍ය බව පෙනී යාමයි. කේතය වෙනස් වන විට සහ ලේඛනය යාවත්කාලීන නොකළ විට, එය පාඨකයා ක්රියාශීලීව නොමඟ යවයි. AI යාවත්කාලීන කිරීම පහසු කරයි: වෙනසක් නිකුත් කර "මෙම වෙනස බලපාන්නේ ලේඛනයේ කුමන කොටස් වලටද?" ඔබට ඇසිය හැක. නමුත් එය යාවත්කාලීන බව සහතික කරන ක්‍රියාවලියයි - ලේඛන යාවත්කාලීන කිරීම කේත වෙනස් කිරීමේ කොටසක් බවට පත් කරන්න (PR හි පිළිගැනීමේ නිර්ණායකය). AI වේගවත් කරයි; කණ්ඩායම විනය ගොඩනඟයි.

අවවාදයයි: README එකක ස්ථාපන පියවර සත්‍යාපනය නොකර පළ නොකරන්න. "බොහෝ විට වැඩ" ලේඛනයක් නව සංවර්ධකයෙකුගේ පළමු දිනය විනාශ කළ හැකි අතර විශ්වාසය බිඳ දැමිය හැකිය. පිරිසිදු පරිසරයක ඔබම පියවර ධාවනය කරන්න.

පොදු වැරදි

• AI වලට ගැලපෙන පරිදි "ඇයි" ලබා ගැනීම. සාවද්‍ය යුක්තිසහගත කිරීම සාධාරණීකරණය නොකිරීමට වඩා නරක ය; කේත හිමිකරු නිර්මාණ හේතුව ලිවිය යුතුය.
• ස්ථාපන පියවර සත්‍යාපනය නොකරයි. වැඩ නොකරන README විශ්වාසය නැති කරයි.
• කේතය පුනරුච්චාරණය කරමින් අනවශ්‍ය අදහස් දැක්වීම. එය ශබ්දය නිපදවයි, සැබෑ "ඇයි" අර්ථ නිරූපණයන් වසන් කරයි.
• ඉලක්කගත ප්‍රේක්ෂකයින් සඳහන් නොකරයි. එය ලියා ඇත්තේ කාටද යන්න පැහැදිලි නැති ලියවිල්ලක් නවකයෙකුට හෝ ප්‍රවීණයෙකුට ප්‍රයෝජනයක් නොවේ.
• ක්‍රියාවලියෙන් යාවත්කාලීන කිරීම වෙන් කිරීම. ලේඛනය කේතය සමඟ යාවත්කාලීන නොකළහොත් එය ඉක්මනින් නොමඟ යවන සුළු වේ.

සාරාංශයක් ලෙස

AI විසින් බොහෝ යාන්ත්‍රික බර ප්‍රලේඛනයෙන් ඉවත් කරයි: ඉක්මන් කෙටුම්පත් README, docstring, API යොමු, චේන්ජ්ලොග් සහ PR විස්තර. නමුත් එය වටිනාම ස්ථරය වන "ඇයි" දැනගත නොහැකි අතර එය සෑදීම භයානක ය. ශ්රම බෙදීම පැහැදිලිය: AI "කුමක්ද/කෙසේද" නිෂ්පාදනය කරයි, ඔබ "ඇයි" එකතු කරයි. ප්‍රේක්ෂකයින් සඳහන් කරන්න, සම්පත් සැපයීම, ව්‍යුහය පැනවීම, ගැලපෙන ස්ථාන සලකුණු කිරීම සහ එක් එක් ස්ථාපන පියවර ඔබම ක්‍රියාත්මක කිරීමෙන් සත්‍යාපනය කරන්න. ලේඛනගත කිරීම කේත වෙනස් කිරීමේ අනිවාර්ය අංගයක් බවට පත් කරන්න.

යෙදුම් කාර්යය

ලේඛන නොමැති හෝ යල් පැන ගිය මොඩියුලයක් හෝ කුඩා ව්‍යාපෘතියක් තෝරන්න. පළමුව AI වෙතින් “ව්‍යුහගත README කෙටුම්පත” (හෝ docstring) අච්චුව සමඟ දළ සටහනක් ජනනය කරන්න; මූලාශ්‍රය සහ ඉලක්කගත ප්‍රේක්ෂකයින් ලබා දීමට වග බලා ගන්න. ඉන්පසු AI විසින් [VERIFY] හෝ [අවශ්‍ය වන්නේ ඇයි] ලකුණු කර ඇති සෑම ලක්ෂ්‍යයක්ම හරහා යන්න: ඇත්ත වශයෙන්ම ස්ථාපන පියවර ධාවනය කර ඔබේම දැනුමෙන් "whys" නිර්මාණය පුරවන්න. පියවර කීයක් සවි කළ යුතුද සහ ඔබ "ඇයි" කීයක් එකතු කළ යුතුද යන්න සටහන් කරන්න.

පිරික්සුම් ලැයිස්තුව

• [ ] ලේඛනගත කිරීමේදී, මම "කුමක්/කෙසේද" සහ "ඇයි" ස්ථර වෙන්කර හඳුනා ගනිමි.
• [ ] මම AI "ඇයි" සෑදෙන්නේ නැත, මම එය එකතු කරමි.
• [ ] මම ප්‍රේරකයට ඉලක්කගත ප්‍රේක්ෂකයින් සහ සත්‍ය මූලාශ්‍ර ගොනු ලබා දෙමි.
• [ ] මම පුද්ගලිකව ක්‍රියාත්මක කිරීමෙන් AI විසින් සලකුණු කරන ලද [VERIFY] ලකුණු සත්‍යාපනය කරමි.
• [ ] මම කේතය නැවත නැවත කරන අනවශ්‍ය අදහස් ඉවත් කරමි.
• [ ] මම ලේඛන යාවත්කාලීන කිරීම කේතය වෙනස් කිරීමේ කොටසක් බවට පත් කරමි.