Kodu açıklamak için yazılan herhangi bir yorumun zamanla geçersiz olması oldukça olasıdır. Zaten bu yüzden kod içerisine az ve öz yorum yazmak sanat yapmaya benzer. Zamanla geçersiz olabilecek yorumları önceden kestirip hiç yazmamaksa, öğrenilebilecek bir refleks gibidir.

Yazılan her yorum, açıklamaya çalıştığı kodun bakımı için harcanan zaman kadar bakım ister. Bu da aslında kod yorumlarını oldukça pahalı birer meta hâline getiriyor. Düşünmeden yazdığımız bir kod yorumunun, belli başlı güncellemelerden sonra geçersiz hâle geldiğini düşünün. Önümüzde iki seçenek olacak:

  1. Yorumun hâlâ geçerli olup olmadığını kontrol etmek, eğer geçersiz hâle gelmişse güncellemek veya gereksiz olduğunu düşünüp silmek.
  2. Yorumu güncellemeye ayıracağımız zamanın önemli olduğunu düşünmek ve olduğu gibi bırakmak.

Argh… İkinci seçeneği düşünmek bile mideme kramp girmesine sebep oluyor. İlk seçeneğin ise bize zaman kaybettireceği aşikar; halbuki daha ilk başta yaptığımız hatayı yapıp kolayca geçersiz olabilecek bir yorum yazmasaydık, ne boşa zaman harcamak zorunda kalacaktık, ne de kodumuzu artık geçersiz olan bir yorumla kirletmeye mecbur kalacaktık.

Bir yorum ne kadar yaşlıysa ve açıklamaya çalıştığı koddan ne kadar uzaksa, yanlış olma olasılığı da o kadar fazladır. Sebebi basit. Yazılımcıların, yorumların doğruluğunu korumaları pek gerçekçi değil.

Clean Code, Robert C. Martin

Örnek

Kolayca geçersiz hâle gelebilecek bir yoruma verilebilecek çokça örnek var; halbuki zor olan, geçerliliğini yitirmeyecek bir yorum örneği verebilmek. Yine de biz, kodumuzu kirleten bu tarz yorumlara bir örnek verelim.

Diyelim ki, kitap ayrıntılarını göstermek için bir sayfamız var. Bu sayfamızın linkini oluşturacak bir fonksiyon yazmaya karar veriyoruz. Fonksiyonu yazdığımız sıralarda veritabanımızda fazla kitabımız yok ve linkte yazar adı kullanmayı mantıklı buluyoruz:

<?php

class Book // Kitap
{
   /**
    * Yazar adını kullanarak kitap için bir link yarat.
    */
   public static function createUrl(string $author /* yazar */): string
   {
      return 'https://kodgrit.com/kitap/'.$author;
   }
}

Şu anda yorum açısından herhangi bir sıkıntımız bulunmuyor. Devam edelim.

Veritabanımıza yeni kitaplar ekliyoruz ve zamanla bir yazarın birden çok kitabının veritabanımızda yer aldığını görmeye başlıyoruz. Yani sadece yazar ismini kullanarak yarattığımız linkler, bizi artık istediğimiz kitaba götürmeyecek. Biz de yazar ismine ek olarak kitap ismini de linke eklemeye karar veriyoruz. Fakat bunu yaparken, fonksiyonun bir nevi dökümanı sayılan yorumu güncellemeyi unutuyoruz.

<?php

class Book // Kitap
{
   /**
    * Yazar adını kullanarak kitap için bir link yarat.
    */
   public static function createUrl(string $author /* yazar */, string $title /* başlık */): string
   {
      return 'https://kodgrit.com/kitap/'.$author.'/'.$title;
   }
}

Her ne kadar kullandığımız argümanlarla güncellemeyi unuttuğumuz yorum arasında farklılıklar olsa da, yorumumuz hâlâ çok kötü durumda değil.

Fakat sonrasında fark ediyoruz ki, veritabanımızdaki kitap isimleri zaten benzersiz. Hem yazar ismini, hem de kitap başlığını kullanarak linkler oluşturmamız, linkleri uzatmaktan başka işe yaramıyor. Biz de artık yazar ismini linklerde kullanmamaya karar veriyoruz. Tabii ki yorumu güncellemeyi yine unutuyoruz.

<?php

class Book // Kitap
{
   /**
    * Yazar adını kullanarak kitap için bir link yarat.
    */
   public static function createUrl(string $title /* başlık */): string
   {
      return 'https://kodgrit.com/kitap/'.$title;
   }
}

Şimdi ne olduğunu gördünüz mü? Yorumda yazana göre yazar adını kullanarak kitap için bir link yaratması gereken fonksiyon, yazar adını argüman olarak almıyor bile.

Kafamız karışıyor. Yazar adının nerde kullanıldığını görmek için fonksiyonun içeriğini okumaya başlıyoruz ama bir türlü bulamıyoruz. Fonksiyon içeriğinin örneğimizdeki gibi tek satır değil de çok daha uzun olduğunu düşünün. Yazar adını bulmak için, sonrasında da bulamayınca yaşayacağımız kafa karışıklığını atmak için harcayacağımız zamanı hayal edin.

Temizlik zamanı

Hatalı bir yorum, hiç yorum olmamasından çok daha zararlıdır.

Clean Code, Robert C. Martin

Daha en başta hataya davetiye çıkarmayı engelleyebilirdik. Fonksiyonumuza yorum olarak “Yazar adını kullanarak kitap için bir link yarat.” yazmak, değişmeye meyilli bir detayı açıklayıcı metin olarak kullanmak demek.

Böyle durumlarda en mantıklısı, detayı hiçbir şekilde açıklamamak. Açıklayıcı bir yoruma sahip olmayan fonksiyona bakan yazılımcı, linkin ne kullanılarak oluşturulduğunu fonksiyon argümanlarına bakarak zaten çözecektir.

<?php

class Book // Kitap
{
   public static function createUrl(string $author /* yazar */): string
   {
      return 'https://kodgrit.com/kitap/'.$author;
   }
}

Böylece, her değişiklikte sadece argüman ismi değişecek ve yorumun doğruluğunu sağlamak için ekstra zaman harcamak zorunda kalmayacağız. Ya da daha kötüsünü, yorumu güncellemeyi unuttuğumuzda yaşatacağımız kafa karışıklığını, en baştan engellemiş olacağız.

Yorum Gönderin

Bir Cevap Yazın

%d blogcu bunu beğendi: