Yazılım kariyerim boyunca birçok farklı geliştirici ile çalıştım, belki de hepsinin kendine özgü bir kod yorum tarzı vardı. Kimisi hiç yorum yazmazdı, kimisi ise tek satır kod için beş satır yorum yazardı. Ben de bu gam içerisinde değişe değişe kendi tarzımı oluşturdum. Bugün geldiğim nokta benim için hâlâ bir son durak sayılmaz; fakat belli bir yarar-zarar dengesini görebildiğimi düşünüyorum.

Kod içerisine yazılan yorumlar, biz yazılımcılara bakımını sağlamamız gereken ek satırlar yaratıyor. Bir kod satırını ya da bir fonksiyonu açıklamak için yorum yazdığımızda, gelecekte dönüp bu kodu güncellediğimizde o yorumu da güncellemek veya en azından güncellememiz gerekip gerekmediğini kontrol etmemiz gerekiyor. Bu da harcamamız gereken ekstra zaman anlamına geliyor. Yani, ekstra maliyet.

Öte yandan, eğer açıklanması gereken bir kod yazmışsak ve bu koda yorum eklememişsek, kaybedeceğimiz zamanın bir önceki duruma göre çok daha fazla olacağını neredeyse emin olarak söyleyebilirim. Gelecekte dönüp bu koda baktığımız zaman ne yaptığını anlayamayacağız. Kodu belki de satır satır okuyup ne yaptığını çözmeye çalışmamız gerekecek.

Halbuki temiz kod, temiz yorum gerektirir. Kod yazarken kullandığımız isimlendirmelerle kodun kendi kendini anlatabilmesini sağlamalı, yorumları ancak ve ancak kodun okuyucuya anlatamadığını anlatmak için kullanmalıyız.

Örnek

Gereksiz yorumlara verilebilecek sürüyle örnek var. Birkaçını listeleyelim:

<?php

$i++; // i'yi artır

/**
 * Argümanları toplar, çıktıyı döndürür
 */
public function t(int $x, int $y): int
{
   return $x + $y;
}

/**
 * @param int $x
 * @return int
 */
public function kare(int $x): int
{
   return $x * $x;
}

İlk kod parçasına yazdığımız yorumun saçmalığı aslında ortada. ++ sembolü yazılımcıların nerdeyse hepsinin çok iyi bildiği bir aritmetik işlem sembolüdür. Bu işlemi anlatmak için yorum yazmaya gerek yok.

İkinci kod parçasında bir fonksiyon tanımladık. Fonksiyon için de bir fonksiyon dökümanı yazdık; yani fonksiyonun ne yaptığını yorum olarak ekledik. Bu her ne kadar yararlı görünse de, aslında kodun kendini anlatmasını sağlayıp yorumları silmek bizim için daha faydalı olacak.

Üçüncü kod parçasında ise, fonksiyon ismi aşağı yukarı ne yapacağını anlatıyor. Bu nedenle herhangi bir yorum eklenmemiş. Fakat fonksiyon dökümanında girdi ve çıktılar yazılmış. Bazı yazılım takımları bunu kendi dinamiklerinde zorunlu tutsa da, bana göre oldukça gereksiz. Girdi ve çıktı tipleri fonksiyon imzasında (public function kare(int $x): int) zaten mevcut.

Temizlik zamanı

Yukarıda verdiğimiz örnekleri temizlediğimizde aşağıdaki gibi bir görünüm elde edeceğiz:

<?php

$i++;

public function topla(int $x, int $y): int
{
   return $x + $y;
}

public function kare(int $x): int
{
   return $x * $x;
}

Peki ya bir yorumun gerekli ya da gereksiz olduğunu nasıl anlarız? Bunun için uygulayabileceğimiz iki aşamalı bir yöntem var:

  1. Yorumladığımız kodu düzenlediğimizde ve değişken ile fonksiyon isimlendirmelerinde iyileştirmeler yaptığımızda kod kendini anlatır hâle gelebiliyor mu? Cevap evetse, yorumu sil gitsin!
  2. Eğer birinci aşamada yorumları elimine edemediysek, sırada yazdığımız yorumun bize ne anlattığına bakacağız. Kodun NE yaptığını değil NEDEN yaptığını anlatıyorsa, bu, gerekli bir yorum olabilir. Eğer yorumumuz NEDEN sorusuna cevap bulmuyorsa, ilk aşamaya gidip kodumuzda biraz daha iyileştirmeler yapmayı deneyebiliriz.

Yorum Gönderin

Bir Cevap Yazın

%d blogcu bunu beğendi: