ஆவணப்படுத்தல், README மற்றும் குறியீடு கருத்துகள்

ஆதாயங்கள்:

• இலக்கு பார்வையாளர்கள் மற்றும் AI உடன் மூலத்தின் அடிப்படையில் README, docstring மற்றும் சேஞ்ச்லாக் வரைவுகளை உருவாக்கும் திறன்
• ஆவணத்தில் 'என்ன/எப்படி' மற்றும் 'ஏன்' அடுக்குகளைப் பிரித்து, மனிதனாக 'ஏன்' சேர்க்கும் திறன்
• தனிப்பட்ட முறையில் அவற்றை இயக்குவதன் மூலம் நிறுவல் படிகளைச் சரிபார்த்தல் மற்றும் ஆவணத்தை குறியீடு மாற்றத்தின் ஒரு பகுதியாக மாற்றுதல்

மென்பொருளின் மிகவும் அடிக்கடி புறக்கணிக்கப்பட்ட ஆனால் நீண்ட காலம் நீடிக்கும் பகுதி ஆவணமாக்கல் ஆகும். குறியீடு பல மாதங்களுக்குப் பிறகும் படிக்கக்கூடியது; எழுதியவர் மறைந்து, சூழல் மறந்து, எழுதியது மட்டும் மிச்சம். ஒரு நல்ல README (புராஜெக்ட் என்றால் என்ன, அதை எவ்வாறு நிறுவுவது மற்றும் இயக்குவது என்பதை விளக்கும் அறிமுக ஆவணம்), விளக்கக் குறியீடு கருத்துகள் மற்றும் புதுப்பித்த API ஆவணம் (இடைமுகத்தை எவ்வாறு பயன்படுத்துவது என்பதை விளக்கும் குறிப்பு) ஆகியவை ஒரு குழுவின் வேகத்தை நேரடியாக தீர்மானிக்கிறது. AI ஆவணத்தில் இருந்து "எழுத்து சோர்வை" நிறைய எடுத்துக்கொள்கிறது - ஆனால் அது ஒரு பொறியுடன் வருகிறது: AI அது என்ன செய்கிறது என்பதை குறியீட்டிலிருந்து ஊகிக்க முடியும், ஆனால் அது ஏன் அவ்வாறு செய்யப்படுகிறது என்பதை அடிக்கடி அறிய முடியாது.

இந்த யூனிட்டில், README, குறியீடு கருத்து, டாக்ஸ்ட்ரிங் (ஒரு செயல்பாடு/வகுப்புக்கு எழுதப்பட்ட கருத்துத் தொகுதி), 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 மணிநேரம் நிறுவுவதில் சிரமப்பட்டனர். குழு நிறுவல் ஸ்கிரிப்ட்கள் மற்றும் pack.json ஐ AI க்கு வழங்கியது மற்றும் ஒரு கட்டமைக்கப்பட்ட README ஐ உருவாக்கியது, பின்னர் ஒரு சுத்தமான கணினியில் படிகளை இயக்கி, விடுபட்ட இரண்டு சார்புகளையும் சேர்த்தது. அடுத்தடுத்த பங்களிப்பாளர்களுக்கான நிறுவல் நேரம் சராசரியாக 25 நிமிடங்களாகக் குறைந்தது.

வழக்கு 2 - உருவாக்கப்பட்ட "ஏன்" பொறி. டெவலப்பர் ஒரு காலக்கெடு மதிப்புக்கு அடுத்துள்ள கருத்தை AIயிடம் கேட்டார் (காலம் முடிந்தது=30). AI ஆனது "அதிக நெட்வொர்க் தாமதத்தை பொறுத்துக்கொள்ள" ஒரு நியாயமான ஆனால் தவறான நியாயத்தை எழுதியது; உண்மையான காரணம் கீழ்நிலை சேவையின் ஒப்பந்த 30-வினாடி வரம்பு. தவறான விளக்கம், ஒரு டெவலப்பர் தேவையில்லாமல் மதிப்பை அதிகரிக்க வழிவகுத்தது, இது ஒரு சம்பவத்திற்கு வழிவகுத்தது. பாடம்: குறியீட்டு உரிமையாளர் நியாயத்தை சரிபார்க்க வேண்டும்.

வழக்கு 3 - டாக்ஸ்ட்ரிங் தரநிலை தானியக்கமாகிவிட்டது. 40 செயல்பாடுகளைக் கொண்ட ஒரு துணைத் தொகுதியில் ஆவணங்கள் இல்லை. AI க்கு திட்ட வடிவம் (கூகுள் ஸ்டைல்) கொடுக்கப்பட்டது மற்றும் ஒவ்வொரு செயல்பாட்டிற்கும் அளவுரு, திரும்ப மற்றும் விதிவிலக்கு விளக்கங்களை உருவாக்கியது; டெவலப்பர் இவற்றை மதிப்பாய்வு செய்து, சில தவறான வகை அறிவிப்புகளைச் சரிசெய்தார். 40 செயல்பாடுகளை ஆவணப்படுத்துவது அரை நாளிலிருந்து ஒரு மணி நேரமாக குறைந்துவிட்டது.

நான்கு நகலெடுக்கக்கூடிய டெம்ப்ளேட்கள்

கட்டமைக்கப்பட்ட README வரைவு:

இலக்கு பார்வையாளர்கள்: {{எ.கா. புதிய பங்களிப்பாளர்}}.கீழே உள்ள கோப்புகளின் அடிப்படையில் README வரைவை எழுதவும். பிரிவுகள்: நோக்கம், அம்சங்கள், தேவைகள், நிறுவல், செயல்பாடு, கட்டமைப்பு, சோதனை, பங்களிப்பு. உண்மையான கோப்புகளிலிருந்து நிறுவல்/இயங்கும் கட்டளைகளைப் பிரித்தெடுக்கவும்; பொருத்துதல். உங்களுக்கு உறுதியாகத் தெரியாத இடங்களை "[VERIFY]" மூலம் குறிக்கவும். ஆதாரம்: {{package.json / scripts / மாதிரி குறியீடு}}

டாக்ஸ்ட்ரிங்/ஏபிஐ குறிப்பு:

{{திட்ட நடை: Google/NumPy/JSDoc}} வடிவத்தில் இந்தச் செயல்பாடுகளுக்கு டாக்ஸ்ட்ரிங்கை எழுதவும்: சுருக்கமான சுருக்கம், அளவுருக்கள் (வகை + பொருள்), திரும்ப, விதிவிலக்குகள், 1 சிறிய உதாரணம். குறியீடு தெளிவாக கூறுவதை மீண்டும் செய்ய வேண்டாம். "ஏன்" தேவைப்படும் வடிவமைப்பு முடிவுகளை "[ஏன் அவசியம்]" எனக் குறிக்கவும், புனையப்பட்ட நியாயத்தை எழுத வேண்டாம்.{{குறியீடு}}

"ஏன்" கருத்துக்கான இடைவெளிகளை அகற்றவும்:

இந்தக் குறியீட்டில், அடுத்த டெவலப்பர் "ஏன் இது அப்படி?" (மேஜிக் எண்கள், அசாதாரண முடிவுகள், தீர்வுகள்). ஒவ்வொன்றிற்கும் SKELETON என்ற கருத்தைக் கொடுங்கள், ஆனால் பகுத்தறிவை காலியாக விடவும்; நியாயத்தை நிரப்புகிறேன்.{{code}}

சேஞ்ச்லாக்/பிஆர் அறிக்கை:

கீழே உள்ள வேறுபாட்டிலிருந்து {{மாற்ற நுழைவு / PR விளக்கம்}} எழுதவும். வடிவம்: என்ன மாறியது (பயனர் மொழியில்), ஏன் (பிரச்சினை: {{...}}), பிரேக்கிங் மாற்றம் (ஏதேனும் இருந்தால்), அது சோதிக்கப்பட்டதா. இலக்கு பார்வையாளர்களுக்கு தொழில்நுட்ப வாசகங்களைச் சரிசெய்யவும்.{{diff}}

பலவீனமான வரியில் / வலுவான வரியில்

பலவீனமானது: "இந்த திட்டத்திற்கு README ஐ எழுதவும்."

வலிமையானது: "இலக்கு பார்வையாளர்கள்: டெவலப்பர் இந்த ரெப்போவை முதன்முறையாக குளோனிங் செய்கிறார். இணைக்கப்பட்டுள்ள package.json, docker-compose.yml மற்றும் scripts/ கோப்புறையின் அடிப்படையில், நோக்கம், தேவைகள், நிறுவல், செயல்பாடு, சோதனை, பங்களிப்பு ஆகிய பிரிவுகளுடன் README வரைவை எழுதவும். இந்தக் கோப்பில் இருந்து எந்த இடத்திலும் கட்டளைகளைப் பிரித்தெடுக்க வேண்டாம். [சரிபார்]."

வலுவான பதிப்பு பார்வையாளர்கள், ஆதாரம், கட்டமைப்பு மற்றும் "அதை உருவாக்கு, குறிக்கவும்" விதியை வழங்குகிறது; ஆவணம் உண்மையான கோப்புகளை அடிப்படையாகக் கொண்டது மற்றும் சரிபார்க்கப்பட வேண்டிய இடங்கள் தெளிவாகத் தெரியும்.

ஆவண வகை

AI நன்றாக இருக்கிறது

மனிதன் சேர்க்கிறான்/சரிபார்க்கிறான்

README நிறுவல்

படி அவுட்லைன்

படிகளை இயக்கவும் மற்றும் உறுதிப்படுத்தவும்

டாக்ஸ்ட்ரிங்/ஏபிஐ

அமைப்பு, அளவுரு, வகை

சரியான வகை மற்றும் "ஏன்"

குறியீடு கருத்து

"அவர் என்ன செய்கிறார்" சுருக்கம்

"ஏன் இது" நியாயம்

சேஞ்ச்லாக்/பிஆர்

முதல் வரைவு

தாக்கம் மற்றும் துல்லியம்

கட்டிடக்கலை முடிவு (ADR)

எலும்புக்கூடு

உண்மையான முடிவுகள் மற்றும் சமரசங்கள்

ஆவணத்திற்கு பராமரிப்பு தேவை

ஒரு ஆவணத்தின் மிகவும் ஆபத்தான அம்சம் அது பொய்யாக இருந்தாலும் அது உண்மையாகத் தோன்றுவதுதான். குறியீடு மாறும்போது மற்றும் ஆவணம் புதுப்பிக்கப்படாவிட்டால், அது வாசகரை தீவிரமாக தவறாக வழிநடத்துகிறது. AI புதுப்பிப்பை எளிதாக்குகிறது: ஒரு வித்தியாசத்தை வெளியிட்டு, "இந்த மாற்றம் ஆவணத்தின் எந்தப் பகுதிகளை பாதிக்கிறது?" நீங்கள் கேட்கலாம். ஆனால் இது புதுப்பித்தலை உறுதிப்படுத்தும் செயல்முறையாகும் - ஆவணப் புதுப்பிப்பை குறியீடு மாற்றத்தின் ஒரு பகுதியாக ஆக்குங்கள் (PR இன் ஏற்றுக்கொள்ளும் அளவுகோல்). AI துரிதப்படுத்துகிறது; அணி ஒழுக்கத்தை உருவாக்குகிறது.

எச்சரிக்கை: README இல் நிறுவல் படிகளைச் சரிபார்க்காமல் வெளியிட வேண்டாம். "அநேகமாக வேலை செய்யும்" ஆவணம் ஒரு புதிய டெவலப்பரின் முதல் நாளைக் கெடுத்து, நம்பிக்கையை சிதைக்கும். சுத்தமான சூழலில் படிகளை நீங்களே இயக்கவும்.

பொதுவான தவறுகள்

• AIக்கு ஏற்றவாறு "ஏன்" பெறுதல். தவறான நியாயப்படுத்தல் நியாயப்படுத்தப்படுவதை விட மோசமானது; குறியீட்டு உரிமையாளர் வடிவமைப்பு காரணத்தை எழுத வேண்டும்.
• நிறுவல் படிகளை சரிபார்க்கவில்லை. வேலை செய்யாத README நம்பிக்கையை அழிக்கிறது.
• குறியீட்டைத் திரும்பத் திரும்பச் சொல்லும் தேவையற்ற கருத்து. இது சத்தத்தை உருவாக்குகிறது, உண்மையான "ஏன்" விளக்கங்களை மறைக்கிறது.
• இலக்கு பார்வையாளர்களைக் குறிப்பிடவில்லை. யாருக்கு எழுதப்பட்டது என்பது தெளிவாகத் தெரியாத ஒரு ஆவணம் புதியவர் அல்லது நிபுணருக்குப் பயன்படாது.
• செயல்முறையிலிருந்து புதுப்பிப்பைப் பிரித்தல். ஆவணம் குறியீட்டுடன் புதுப்பிக்கப்படாவிட்டால், அது விரைவில் தவறாக வழிநடத்தும்.

சுருக்கமாக

AI ஆனது பெரும்பாலான இயந்திரச் சுமையை ஆவணப்படுத்தலில் இருந்து எடுக்கிறது: விரைவான வரைவுகள் README, docstring, API குறிப்பு, சேஞ்ச்லாக் மற்றும் PR விளக்கங்கள். ஆனால் அது "ஏன்" என்பதை அறிய முடியாது, இது மிகவும் மதிப்புமிக்க அடுக்கு ஆகும், மேலும் அதை உருவாக்குவது ஆபத்தானது. உழைப்பைப் பிரிப்பது தெளிவாக உள்ளது: AI "என்ன/எப்படி" என்பதை உருவாக்குகிறது, நீங்கள் "ஏன்" சேர்க்கிறீர்கள். பார்வையாளர்களைக் குறிப்பிடவும், வளங்களை வழங்கவும், கட்டமைப்பைத் திணிக்கவும், பொருந்தக்கூடிய இடங்களைக் குறிக்கவும் மற்றும் ஒவ்வொரு நிறுவல் படியையும் நீங்களே இயக்குவதன் மூலம் சரிபார்க்கவும். குறியீட்டு மாற்றத்தின் ஒருங்கிணைந்த பகுதியாக ஆவணமாக்குங்கள்.

விண்ணப்ப பணி

ஆவணங்கள் விடுபட்ட அல்லது காலாவதியான தொகுதி அல்லது சிறிய திட்டத்தைத் தேர்ந்தெடுக்கவும். முதலில் "கட்டமைக்கப்பட்ட README வரைவு" (அல்லது docstring) டெம்ப்ளேட்டுடன் AI இலிருந்து ஒரு வெளிப்புறத்தை உருவாக்கவும்; ஆதாரத்தையும் இலக்கு பார்வையாளர்களையும் கொடுக்க மறக்காதீர்கள். AI குறிப்பிட்டுள்ள ஒவ்வொரு புள்ளியிலும் செல்லவும் [சரிபார்க்கவும்] அல்லது [ஏன் தேவை]: உண்மையில் அமைவு படிகளை இயக்கவும் மற்றும் உங்கள் சொந்த அறிவைக் கொண்டு "whys" வடிவமைப்பை நிரப்பவும். எத்தனை படிகள் சரி செய்யப்பட வேண்டும் மற்றும் எத்தனை "ஏன்" சேர்த்தீர்கள் என்பதைக் கவனியுங்கள்.

சரிபார்ப்பு பட்டியல்

• [ ] ஆவணத்தில், நான் "என்ன/எப்படி" மற்றும் "ஏன்" அடுக்குகளை வேறுபடுத்துகிறேன்.
• [ ] நான் AI ஐ "ஏன்" என்று உருவாக்கவில்லை, அதை நானே சேர்க்கிறேன்.
• [ ] இலக்கு பார்வையாளர்கள் மற்றும் உண்மையான மூல கோப்புகளை நான் வரியில் கொடுக்கிறேன்.
• [ ] தனிப்பட்ட முறையில் செயல்படுத்துவதன் மூலம் AI ஆல் குறிக்கப்பட்ட [VERIFY] புள்ளிகளை நான் சரிபார்க்கிறேன்.
• [ ] குறியீட்டை மீண்டும் செய்யும் தேவையற்ற கருத்துகளை நான் நீக்குகிறேன்.
• [ ] குறியீட்டு மாற்றத்தின் ஒரு பகுதியாக ஆவணப் புதுப்பிப்பை உருவாக்குகிறேன்.