Izohlar

Izohlar (comments) — kodda dvigatel e'tiborsiz qoldiradigan matn. Ular dasturchilar uchun tushuntirish yozadi. Ammo yaxshi izoh yozish — alohida mahorat. Ko'p izoh har doim ham yaxshi emas.

Izoh sintaksisi

JavaScript'da izohlar ikki xil bo'ladi:

// bir qatorli izoh

/*
  ko'p qatorli
  izoh
*/

let x = 5; // qator oxirida ham yozish mumkin

Yomon izohlar

Ko'plab yangi dasturchilar izohlarni "kod nima qilyapti" ni tushuntirish uchun ishlatadi. Masalan:

// yomon: kod nima qilishini takrorlaydi
let i = 0; // i ni nolga tenglashtiramiz
i = i + 1; // i ni bittaga oshiramiz

Bunday izohlar deyarli befoyda — ular kodda allaqachon ko'rinib turgan narsani takrorlaydi. Yaxshi kodning o'zi "o'zini o'zi tushuntiradi" (self-descriptive) bo'lishi kerak.

Kodni izoh o'rniga qayta yozish

Ba'zan chalkash kod bo'lagini izohlash o'rniga, uni alohida mazmunli nomli funksiyaga ajratish yaxshiroq:

// izoh bilan
// birlamchi son ekanligini tekshiramiz
for (let i = 2; i < n; i++) {
  if (n % i === 0) return false;
}

// yaxshiroq: mazmunli nomli funksiya
function birlamchiSonmi(n) {
  for (let i = 2; i < n; i++) {
    if (n % i === 0) return false;
  }
  return true;
}

Endi funksiya nomining o'zi maqsadni tushuntiradi — izoh kerak emas.

Yaxshi izohlar: nima uchun?

Foydali izohlar odatda nima qilinayotganini emas, nega shunday qilinayotganini tushuntiradi. Bu "yuqori darajadagi" izohlar. Ular quyidagilarni yoritadi:

• Arxitektura — komponentlar qanday o'zaro ishlashi, ma'lumot oqimi;
• Nega aynan bu yechim? — nima uchun boshqa, aftidan sodda usul tanlanmagan;
• Nozik jihatlar — ochiq ko'rinmaydigan, lekin muhim tafsilotlar.

// yaxshi: NEGA shunday qilinganini tushuntiradi
// Bu yerda tsiklni teskari tartibda aylantiramiz,
// chunki bu massivdan element o'chirishda
// indekslarning "sirg'anib ketishini" oldini oladi.
for (let i = arr.length - 1; i >= 0; i--) {
  if (arr[i] === null) arr.splice(i, 1);
}

Funksiyalarni hujjatlashtirish

Funksiya nima qilishini, qanday parametr olishini va nima qaytarishini tavsiflash uchun maxsus JSDoc uslubi bor. Bu izohlarni muharringiz o'qib, avtomatik yordam ko'rsatadi:

/**
 * n-darajaga ko'tarish.
 *
 * @param {number} x Ko'tariladigan son.
 * @param {number} n Daraja (butun son bo'lishi kerak).
 * @return {number} x ning n-darajasi.
 */
function pow(x, n) {
  let natija = 1;
  for (let i = 0; i < n; i++) {
    natija *= x;
  }
  return natija;
}

Xulosa

Yaxshi izoh belgisi — bu izohning yo'qligi. Kodning o'zi imkon qadar tushunarli bo'lsin. Kerakli izohlar:

• Arxitekturani yuqori darajada tavsiflaydi;
• Kod nima qilishini emas, nega shunday qilinganini tushuntiradi;
• Ochiq ko'rinmaydigan nozik jihatlarni yoritadi;
• Funksiyalarni JSDoc orqali hujjatlashtiradi.

Kerakmas izohlar esa — kod nima qilishini so'zma-so'z takrorlaydi va faqat chalg'itadi.