Ինքնաբացատրող կոդի առասպելը
Եթե ձեր կոդն ինքն իրեն փաստաթղթավորում է, կարելի՞ է մեկնաբանություններ չգրել։ Ոչ ամբողջովին. ահա պատճառաբանությունը։
Կամ, ավելի ճշգրիտ ասած՝ դա հիանալի նպատակ է, որին երբեմն կարելի է հասնել, բայց այն չի ազատում ձեզ կոդը մեկնաբանելուց։ Յուրաքանչյուր ոչ ակնհայտ հատված միևնույն է արժանի է մեկնաբանության, և դրանք ավելի շատ են, քան կարելի է սպասել։ Որպես կոդի հեղինակներ՝ մեր գլխավոր հոգսը, ի վերջո, կոդը կարդացողի հարմարավետությունն է. ամենից առաջ մենք ուզում ենք, որ ուրիշները կամ ապագայում մենք ինքներս կարողանանք հասկանալ այն։
Ինքնաբացատրող կոդի հիմքում ընկած սկզբունքները, բնականաբար, ճիշտ են (և արդարացնում են իրենց նաև այլ պատճառներով). ֆունկցիաներն ու մեթոդները փոքր պահել, յուրաքանչյուր օրվա կեսը նվիրել ճիշտ անուններ ընտրելուն, նախագծել համապատասխան աբստրակցիայի սահմաններ և գրել թեստեր, որոնք և ստուգում են կոդի վարքը, և հանդես են գալիս որպես կոմպիլացվող փաստաթղթավորում։
Այդուհանդերձ, միշտ կլինեն կոդի հատվածներ, որոնք կարդացողներին գլուխ քորել են տալիս՝ մտածելով, թե ինչպես լավագույնս ցույց տան հեղինակին իրենց «երախտագիտությունը»։ (Պատահում է, որ հենց այդ հատվածներն են, որ պետք է ձեռքով գրել, այլ ոչ թե ստանալ ChatGPT-ից։)
Այդպիսի հատվածը կարող է լինել, օրինակ, արտառոց երրորդ կողմի սերվիսի հետ ինտեգրացիան. նկարագրեք այդ արտառոցությունը։ Կամ բիզնես կանոն, որը կոդի վերածվելուց հետո տարօրինակ բիթային մանիպուլյացիայի է նման, բայց իսկապես պետք է հենց այդպես գրվի, քանի որ գտնվում է կրիտիկական ճանապարհի վրա. բացատրեք «ինչու»-ն։ Մեր ծրագրավորման լեզուները բավական արտահայտիչ են, բայց սահմաններ ունեն, և երբ հասնում եք դրանց, չվարանեք դիմել մեկնաբանության։
Այս ամենը կարող է ակնհայտ թվալ, բայց ինչպե՞ս նկատենք մյուս հատվածները, որոնք մեկնաբանության կարիք ունեն։ Որպես առաջին մոտարկում՝ ապավինեք ողջամտությանը (օրինակ՝ Person getPerson()-ը gets the person-ով փաստաթղթավորելը չպետք է անցնի այս զտիչը)։ Այդուհանդերձ, մենք կարող ենք չափից ավելի լավատես լինել մեր փայլուն նոր աբստրակցիայի ընթեռնելիության մասին։
Ահա թե ինչու որպես երկրորդ մոտարկում՝ արժե նայել կոդի վերանայման մեկնաբանություններին, օրինակ՝ pull request-ների (PR) / merge request-ների քննարկումներին։ Եվ խնդրեք ձեր վերանայողներին մատնանշել այն տեղերը, որտեղ կոդի ընթացքը դժվար էր հետևել։
Երբ PR-ում կոդի կոնկրետ հատվածի շուրջ քննարկում է ծագում, այն միշտ պետք է հանգեցնի կոդի ռեֆակտորինգի, դրան մեկնաբանություն ավելացնելուն, կամ երկուսին էլ։ Հենց այն փաստը, որ PR-ն ընդհանրապես մեկնաբանություններ կամ հարցեր է առաջացնում, ցույց է տալիս, որ կոդային բազան իրականում ինքնաբացատրող չէ։
PR-ների և issue-ների քննարկումները հարմար են և օգնում են կրճատել հետադարձ կապի ցիկլը։ Օգտագործեք դրանցում պարունակվող տեղեկատվությունը և թույլ մի տվեք, որ այն մահանա։ Մի վախեցեք կրկնօրինակելուց. ապագայում կոդը փոփոխելու բախտ ունեցողը կկարդա միայն կոդը. նա չի փորփրի PR-ների միաձուլման ողջ պատմությունն ու դրանց կից քննարկումները։ Եթե, իհարկե, նա իսկապես չզայրանա և չհուսահատվի, բայց փորձենք կանխել դա։
Առնվազն նրան որոշակի համատեքստ տվեք՝ issue-ի համարի կամ հետադարձ հղման տեսքով։ Է՛լ ավելի լավ է՝ համապատասխան տեղեկատվությունը դնել ուղիղ կոդի մեջ։ Issue-ներն ու PR-ները մոռացվում են, հենց որ միաձուլվում են։
«Բայց սպասեք, կարող եք առարկել, փաստաթղթավորումը հնանում է»։ Ճիշտ է, և մեկնաբանությունները դուրս են գալիս համաժամանակությունից իրենց նկարագրած կոդի հետ։ Դա անշուշտ խնդիր է։ Սակայն դա հատկապես ճիշտ է, երբ փաստաթղթավորումը գտնվում է իր նկարագրածից հեռու։ Մեկնաբանություններն ավելի լավ դիրքում են. կարող եք դրանք տեղադրել անմիջապես տրամաբանության կողքին, ինչը նվազեցնում է հնանալու վտանգը։
Եվս մեկ փաստարկ կոդի մեկնաբանությունների օգտին. երբ խոսքը հենց սկզբնական կոդի մասին է, սկզբնական կոդը պետք է լինի ճշմարտության կենտրոնական աղբյուրը։ Մենք արդեն նշել ենք, որ մի քանի տեղում՝ PR-ների մեկնաբանություններում, issue-ների նկարագրություններում և սկզբնական կոդում, ցրված տեղեկատվության մեջ դժվար է կողմնորոշվել։ Դրան գումարած՝ այն մասամբ ենթակա է vendor lock-in-ի։ Git-ը բաշխված տարբերակների կառավարման համակարգ է, ուստի յուրաքանչյուրն ունի ամբողջական, պարբերաբար թարմացվող կրկնօրինակ, բայց, իհարկե, միայն այն տեղեկատվության, որն իրականում գտնվում է git-ում։
PR-ները, issue-ները և մեր գլուխները շատ տեղեկատվություն են պահում. մի թողեք այն այնտեղ։ Եվ թույլ մի տվեք, որ այն մահանա։ Ամփոփելով՝
- նույնիսկ ամենամաքուր կոդային բազաներին մեկնաբանություններ են պետք
- կոդի վերանայման մեկնաբանություններին վերաբերվեք որպես ազդանշանների, թե որտեղ է պետք ռեֆակտորինգ կամ մեկնաբանություն
- «ինչու»-ն ամրագրեք՝ օգտագործելով այն issue-ի/բագի հաշվետվության համատեքստը, որի վրա աշխատում եք
- ցանկացած կարևոր բան issue-ից կամ PR/MR քննարկումից տեղափոխեք կոդային բազա՝ անվանումների, կոդի կառուցվածքի կամ մեկնաբանությունների միջոցով
- սկզբնական կոդը դարձրեք ճշմարտության կենտրոնական աղբյուրը սկզբնական կոդի մասին։