Sharhlarni kodga kiritish: yaxshi, yomon va chirkin.

Clint Eastwood in

Agar siz buni oldinroq eshitgan bo'lsangiz, meni to'xtating ...

"Yaxshi kod bu o'z-o'zini hujjatlashtirishdir."

20 kun yashash uchun kod yozganingizda, bu men eng ko'p eshitgan gap.

Bu klishe.

Va ko'plab klişelardek, u uchun haqiqat yadrosi mavjud. Ammo bu haqiqat shu qadar buzilganki, iborani ishlatadigan ko'p odamlar bu nimani anglatishini tushunmaydilar.

Bu rostmi? Ha.

Bu sizning kodingizni hech qachon sharhlamasligingizni anglatadimi? Yo'q.

Ushbu maqolada sizning kodingizni sharhlash haqida gap ketganda, yaxshi, yomon va xunukni ko'rib chiqamiz.

Yangi boshlanuvchilar uchun kod sharhlarining ikki xil turlari mavjud. Men ularni hujjat izohlari va tushuntirish sharhlari deb atayman.

Hujjatlar sharhlari

Hujjatlar bo'yicha sharhlar sizning dastlabki kodingizni iste'mol qiladigan, ammo uni o'qimaydigan har bir kishiga mo'ljallangan. Agar siz boshqa ishlab chiquvchilar foydalanadigan kutubxona yoki ramka qurayotgan bo'lsangiz, sizga API hujjatlarining ba'zi shakli kerak bo'ladi.

Sizning API hujjatingiz dastlabki kodidan qanchalik uzoq bo'lsa, vaqt o'tishi bilan eskirishi yoki noto'g'ri bo'lishi ehtimoli ko'proq. Buni yumshatish uchun yaxshi strategiya bu hujjatni to'g'ridan-to'g'ri kodga kiritish va keyin uni olish uchun vositadan foydalanishdir.

Bu erda mashhur Lodash nomli JavaScript kutubxonasidagi hujjatlar sharhining namunasi.

Agar siz ushbu sharhlarni ularning onlayn hujjatlari bilan taqqoslasangiz, u aniq mos kelishini ko'rasiz.

Agar siz hujjatlarni izohlar bilan yozsangiz, siz ularning izchil standartga muvofiqligini va har qanday chizilgan izohlardan osongina ajralib turishini ta'minlashingiz kerak, siz qo'shimcha qilishingiz mumkin. Ba'zi mashhur va yaxshi qo'llab-quvvatlanadigan standartlar va vositalarga JavaScript uchun JSDoc, dotNet uchun DocFx va Java uchun JavaDoc kiradi.

Ushbu turdagi sharhlarning salbiy tomoni shundaki, ular sizning kodingizni juda "shovqinli" qiladi va uni saqlashda faol ishtirok etgan har bir kishi uchun o'qishni qiyinlashtiradi. Yaxshi xabar shundaki, ko'pchilik kod muharrirlari "kodni yig'ish" ni qo'llab-quvvatlaydilar, bu bizga sharhlarni buzishimizga imkon beradi va biz kodga e'tibor qaratishimiz mumkin.

Visual Studio Code-da kodlarni yig'ish bilan sharhlarni yig'ish.

Tushuntirish sharhlari

Aniqlash bo'yicha sharhlar sizning kodingizni saqlash, qayta ishlash yoki kengaytirishga muhtoj bo'lgan har bir kishiga (kelgusida o'zingiz uchun) mo'ljallangan.

Ko'pincha, tushuntirish sharhlari kod hididir. Bu sizning kodingiz juda murakkab ekanligini aytadi. Siz tushuntirish sharhlarini olib tashlashingiz va kodni soddalashtirishga harakat qilishingiz kerak, chunki "yaxshi kod o'z-o'zini hujjatlashtirishdir".

Yomon misol - bu juda qiziqarli bo'lsa-da, tushuntirish izohi.

/ *
 * Bo'shliqlar bilan almashtiring
 * holatlarda qavslar
 * joylarda qavslar
 * stazga olib keladi.
** /
$ str = str_replace (qator ("\ {", "\}"), "", $ str);

Bir oz chalkash iborani aqlli qofiya bilan - amfibra o'lchovi bilan bezashning o'rniga, muallif kodni o'zi o'qishni va tushunishni osonlashtiradigan funktsiyaga vaqt sarflashi yaxshiroq bo'lar edi. Balki sanitizeInput nomli boshqa funktsiyadan chaqirilgan removeCurlyBraces nomli funktsiya kerakmi?

Meni adashtirmang, vaqti-vaqti bor, ayniqsa, og'ir ish bilan ovora bo'lganingizda - ozgina hazil in'omi qalb uchun yaxshi bo'lishi mumkin. Ammo siz yomon kodni tuzish uchun kulgili sharh yozsangiz, aslida odamlarni keyinchalik kodni tuzatish va tuzatish ehtimoli kamroq bo'ladi.

Siz haqiqatan ham ushbu aqlli kichik qofiyani o'qish quvonchining kelajakdagi barcha kodlovchilarini o'g'irlashda aybdor bo'lishni xohlaysizmi? Aksariyat kodlovchilar kod hidiga e'tibor bermay, qoqilib ketaveradilar.

Ortiqcha sharhga duch kelgan paytlaringiz ham bor. Agar kod allaqachon sodda va ravshan bo'lsa, izoh qo'shishning hojati yo'q.

Xuddi shunday, bema'ni ish qilmang:

/ *
yosh sonini 32 ga qo'ying
* /
int yoshi = 32;

Kodni o'zi nima qilishidan qat'iy nazar, vaqti-vaqti bilan aniqlik izohi berilishi kerak.

Odatda, bu sizga intuitiv bo'lmagan echimga ba'zi kontekstni qo'shish kerak bo'lganda yuz beradi.

Lodashdan yaxshi misol:

addSetEntry funktsiyasi (to'plam, qiymat) {
  / *
   "Set.add" ni qaytarmang, chunki IE 11-da bu mumkin emas.
  * /
  set.add (qiymat);
  qaytish to'plami;
}

Shuningdek, shunday paytlar ham bo'ladiki - ko'p o'ylar va tajribalardan so'ng muammoning sodda bo'lib tuyulgan yechimi aslida eng yaxshisi ekan. Ushbu stsenariylarda ba'zi boshqa koderlar sizdan ko'ra aqlli ekanligi haqida o'ylashlari va muomala qilishlari mumkin, faqat sizning yo'lingiz eng yaxshi yo'l ekanligini bilib olish uchun.

Ba'zan bu boshqa kodlovchi sizning kelajagingiz.

Bunday hollarda har kimga vaqtni tejash va xijolat bo'lish va sharh qoldirish yaxshi.

Quyidagi masxara-sharh ushbu stsenariyni mukammal darajada ushlaydi:

/ **
Hurmatli xizmat ko'rsatuvchi:
 
Ushbu tartibni "optimallashtirish" ga harakat qilganingizdan so'ng,
va qanday dahshatli xato bo'lganini angladik.
iltimos, quyidagi hisoblagichni ogohlantirish sifatida oshiring
keyingi yigitga:
 
jami_hours_wasted_here = 42
** /

Shunga qaramay, yuqorida aytib o'tilganlar foydali bo'lishdan ko'ra kulgili bo'lish haqida ko'proq. Ammo siz izoh qoldirishingiz kerak, agar siz buni sinab ko'rsangiz va rad qilsangiz, boshqalarga aniq ko'rinadigan "yaxshiroq echim" berilmasligi kerak. Va qilganingizda, sharhda siz qanday echimni sinab ko'rganingizni va nima uchun bunga qarshi qaror qilganingizni ko'rsatishingiz kerak.

Mana JavaScriptda oddiy misol:

/ *
global isFinite () dan foydalanmang, chunki u nol qiymatlarga to'g'ri keladi
* /
Number.isFinite (qiymat)

Xunuk

Shunday qilib, biz yaxshi va yomonni ko'rib chiqdik, ammo xunuk-chi?

Afsuski, har qanday ishda o'zingizning hafsalangiz pir bo'lishi mumkin va yashash uchun kod yozayotganda, bu umidsizlikni kod sharhlariga kiritishingiz mumkin.

Etarli kod bazalari bilan ishlang, shunda siz bema'ni va tushkunlikdan tortib to qorong'i va xayoliygacha bo'lgan sharhlarni uchratasiz.

Ishlar zararsiz bo'lib tuyuladi ...

/ *
Ushbu kod yutadi, siz buni bilasiz va men bilaman.
Keyinroq meni ahmoq deb chaqiring.
* /

… Degan ma'noni anglatadi

/ *
Sinf Richardni f *** ing ahmoqligi sifatida qayta ishlashga odatlangan
* /

Bu narsalar kulgili bo'lib tuyulishi mumkin yoki hozirgi paytda bir oz umidsizlikni ketkazishga yordam berishi mumkin, lekin ular ishlab chiqarish kodiga kiritilganda, ularni yozgan koderni va ularning ish beruvchilarini professional va achchiq ko'rinishga olib keladi.

Buni qilmang.

Agar sizga ushbu maqola yoqsa, iltimos, qarsaklar ikonkasini bir necha marta silkiting va so'zni tarqatishga yordam bering. Va agar siz shunga o'xshash narsalarni o'qishni istasangiz, quyida keltirilgan haftalik Dev Mastery nashriga yoziling.