Yorumlar

Kod yaps blmnden de bildiiniz zre, yorumlar tek satr // olabilecei gibi birden ok satr da olabilir /* .. */. Genelde yorum satrlar kodun nasl ve niin altn anlatmak iin kullanlr.

lk grte yorum yapmann gereklilik olduu aikardr. Fakat programlama yeni balayanlar bunu ilk nce genelde yanl anlamaktadrlar.

Kt Yorum

Programlamaya yeni balayanlar yorumlar genelde kodda ne oluyor'u anlatmak iin kullanrlar. rnein:

// Bu kodu bunu unu yapacak  vs. vs.
// ...vs. vs. vs.
ar;
karmak;
kod;

Fakat iyi kod aslnda kendi kendini aklayan koddur. Yorum satrlarnn olabildiince az olmas beklenir. Gerekten, kod yorum satr olmadan da kolayca anlalabilir olmal.

Bunun iin harika bir kural var: Eer bir kod yorum yapmay gerektirecek kadar karmaksa, kodu tekrar yazmanzda yarar var

zm: Fonksiyonlar darya atn.

Bazen kod paralarn fonksiyonlarla deitirmek yarar salar, rnein:

function asalSayilariGoster(n) {
  sonrakiAsal:
  for (let i = 2; i < n; i++) {

    // i asal m kontrol et
    for (let j = 2; j < i; j++) {
      if (i % j == 0) continue sonrakiAsal;
    }

    alert(i);
  }
}

Daha iyisi bu fonksiyonun dna asalMi diye ayri bir fonksiyon yazmak:

function asalSayilariGoster(n) {

  for (let i = 2; i < n; i++) {
    if (!asalMi(i)) continue;

    alert(i);
  }
}

function asalMi(n) {
  for (let i = 2; i < n; i++) {
    if (n % i == 0) return false;
  }

  return true;
}

Bylece kodu daha kolay bir ekilde anlayabilirsiniz. Fonksiyonun kendisi aslnda yorum oldu. Bu tr fonksiyonlara kendi kendini aklayan fonksiyon denir.

zm: yeni fonksiyon yaz

Eer aadaki gibi uzun bir kod sayfanz varsa:

// here we add whiskey
for(let i = 0; i < 10; i++) {
  let damla = ayranDoldur();
  kokla(damla);
  ekle(damla, bardak);
}

// here we add juice
for(let t = 0; t < 3; t++) {
  let domates = domatesDoldur();
  kontrolEt(domates);
  let domatesSuyu = bastir(domates);
  ekle(domatesSuyu, bardak);
}

// ...

Bu fonksiyonlar yeniden dzenlemek daha iyi bir yntem olabilir.

ayranEkle(bardak);
domatesEkle(bardak);

function ayranEkle(kap) {
  for(let i = 0; i < 10; i++) {
    let damla = ayranDoldur();
    //...
  }
}

function addJuice(kap) {
  for(let t = 0; t < 3; t++) {
    let domates = domatesDoldur();
    //...
  }
}

Tekrardan sylemek gerekirse nelerin olup bittiini yorum deil, fonksiyonun kendisi sylemeli.Ayrca kod yaps fonksiyonlar eklinde ayrk olduunda daha dzgn olur. Her fonksiyonun ne argman ald ne geri dndrd bellidir.

Gerekte neyin olup bittiini syleyen yorumu tamamen karmak olanakszdr. Bazen karmak algorimalar olabilir. Bazen akllca yaplm ksayollar olabilir. Fakat genel olarak kod basit ve kendi kendini aklayc olmal.

yi yorum

Peki, fonksiyonun ne yaptn anlatan yorumlar kt ise, hangi yorumlar iyi?

Mimariyi tanmla

st seviyede bileenlere genel bak, nasl birbirleriyle iletiim kurduklar, farkl durumlarda akn nasl deiecei gibi konular anlatlmaldr. Ksaca ku bak kodun ne yaptn anlatmalsnz. Bununla ilgili ema diline UML bakabilirsiniz. Kesinlikle stnde allmaya deer.

Fonksiyon kullanmn dkmante etme

Fonksiyonu dkmante edebilmek iin standart zel bir yazm vardrJSDoc. Fonksiyon: kullanm, parametreler, dnen deer.

rnein:

/**
 * X'in n'inci ssn hesaplayp geri dner.
 *
 * @param {number} x ss bulunacak say.
 * @param {number} n s deeri doal say olmal.
 * @return {number} x ssn hesaplanm hali.
 */
function ushesapla(x, n) {
  ...
}

Bu yorumlar bize bu fonksiyonun amacnn ne olduunu koda bakmadan anlatr.

Bu arada WebStorm gibi editrler size JSDoc yazma konusunda yardmc olur. Otomatik olarak kodu kontrol edebilir.

Ayrca JSDoc 3 gibi aralar dorudan HTML formatnda dkmantasyon yapmanz salar. Daha fazla bilgiyi http://usejsdoc.org/ adresinden okuyabilirsiniz.

Neden bu yntemle zld?

Ne yazld nemlidir. Fakat ne yazlmad nelerin olup bittii hakknda belki daha nemlidir. Bu problem neden bu ekilde zld? Size bunun cevabn kod veremez.

Eer problemi zmek iin birok yol varsa neden bu yolu setiniz? zellikle cevabn ak olmad durumlarda bu soru nemli.

Byle yorumlarn yaplmad durumlarda aadakiler meydana gelebilir:

1. Siz ( veya arkadanz ) editr atnda, yazlan kodun vasat olduunu grebilir dnebilir.
2. yle dnebilirsiniz: O zaman da ne salakmm, imdi akllandm harikayim artk ve kodu tekrar daha iyi ve doru ekilde yazarsnz.
3. Tekrar yazma istei iyidir. Fakat daha ak ve doru zm aslnda eksiktir. Daha nce zaten en iyi ekilde yazmaya almtn. Bunu yaparken zaman harcadn ve imdi bu sre pe gitti.

zm aklayan yorumlar gerekten ok nemlidir. Gelitirmeyi doru yoldan yapmanza byk katk salar.

Eer kodda nerede kullanldna veya zelliklerine dair ipular bulmak zor ise yorum yapmak gerekten emee deerdir.

zet

yi programcnn en nemli zelliklerinden biri yorumlarnn varl, hatta yokluudur.

yi yorumlar kodun bakmnn dzgn bir ekilde yaplmasn salar. Daha sonra geri dnldnde her eye daha etkin bir ekilde balanr.

Bunlar yorum olarak yazn:

• Genel mimari, ince detayna kadar deil sadece ku bak
• Fonksiyon kullanm.
• nemli zmler, zellikle zm ok ak deilse

Bunlar iin yorum yazmayn:

• Kodun nasl altn, ne yaptn anlatmak iin
• Sadece eer yorum yazmadan fonksiyon kendisini anlatamyorsa bunlar yazn.

Yorumlar ayrca otomatik bir dkmantasyon oluturmanzda yardmc olur. rnein JsDoc3 arac ile yorumlarnzdan HTML dkmantasyonu kts alabilirsiniz. ( dier formatlar da destekler )