Yazılımcılar olarak ürettiklerimizle gurur duymak bizim için bu işin getirdiği ek faydalardan biri. Ne de olsa hiç yoktan yeni bir şey yaratıyoruz ve bu yarattığımız şeyin çalıştığına tanık oluyoruz. Bundan daha keyifli ne olabilir ki?

Ürettiklerimize ek olarak, nasıl ürettiğimizin de önemi var. Hele ki yazdığımız kodun oldukça şık ve zarif olduğunu düşünüyorsak, yarattığımız somut şey her ne ise, onu çalıştıran koddan da aynı şekilde gurur duyuyoruz. Bu nedenle kod parçalarında yazar adı görmeye oldukça alışkınız:

<?php

// Author, Yazar: Ekin Öcalan
// Date, Tarih: Mar 9, 2019

Çoğu yazılımcı, ki bu gruba geçmişte ben de dahildim, bu gurur hissiyatını yorumlara da taşımaktan çekinmez. Şık ve zarif bir kod parçasının kendi kendini anlatabilmesini bekleriz; halbuki biz yazılımcılar, yazdığımız kod parçasının ne denli akıllıca olduğunu başkalarına da göstermek için kendimizi o yorumu yazmaktan alıkoyamayız. Bunu da havalı bir şekilde yapmaya bayılırız. 🙂

Fakat gerçek şu ki, kod parçaları bizim egomuzu yansıtacak mantıklı birer meta değil. Eğer kodumuz kendini yeterince açık anlatamıyorsa, yorum yazmak yerine yazdığımız kodu düzeltmek ilk deneyeceğimiz şey olmalı. Eğer başarısız olursak, yorumlar elbette ki yardımımıza koşacaktır. Fakat burda önemli olan şey egomuzu yansıtmak değil, yorumun okuyucular tarafından kolayca anlaşılabilmesini sağlamak.

Eğer bir yorum yazacaksak, zaman ayırıp en iyi şekilde yazmaya özen göstermeliyiz.

Örnek

Konu yorum olunca verilebilecek çok fazla örnek oluyor. Gelin birkaçına beraber bakalım:

<?php

abstract class Book // Kitap
{
   /**
    * Kitaplardan oluşan bir koleksiyon alır,
    * bu kitapları tek tek veritabanına ekler.
    * Eklediği her kitap, veritabanında listenin
    * sonuna eklenir.
    */
   public static function pushAll(array $books): void;

   /**
    * Listenin sonuna bir kitap ekler.
    */
   public static function push(Book $book): void;

   /**
    * Sondaki kitabı döndürür. Fakat bunu yapabilmesi için
    * önce push() metoduyla bir kitap eklemeniz gerekir.
    * Evet, sana diyorum. Kitap eklemeden kitap almayı
    * beklemiyordun değil mi? :-) Hadi sana bir de kolaylık
    * yaptım, pushAll() diye bir fonksiyon ekledim. Koyacak
    * birden fazla kitabın varsa tek tek uğraşmazsın. ;-)
    */
   public static function pop(): Book;
}

Temizlik zamanı

Fonksiyonlarımızın tek tek üzerinden geçelim:

/**
 * Kitaplardan oluşan bir koleksiyon alır,
 * bu kitapları tek tek veritabanına ekler.
 * Eklediği her kitap, veritabanında listenin
 * sonuna eklenir.
 */
public static function pushAll(array $books): void;

İlk hata ilk cümlede karşımıza çıkıyor. array, Türkçe’ye dizi olarak çevrilmiş bir veri yapısıdır. Koleksiyon ise bambaşka bir şey. Yorumlarda doğru terimleri kullanmalıyız.

/**
 * Kitaplardan oluşan bir dizi alır,
 * bu kitapları tek tek veritabanına ekler.
 * Eklediği her kitap, veritabanında listenin
 * sonuna eklenir.
 */
public static function pushAll(array $books): void;

İkinci hata, yorumlarda veritabanından bahsetmek. Fonksiyonun içeriğini bilmiyoruz; dolayısıyla fonksiyon veritabanı kullanıyor mu onu da bilmiyoruz. Veritabanı, bir veri depolama yöntemidir ve alternatifleri vardır. İlerde veritabanını farklı bir veri depolama yöntemiyle değiştirmemiz olasılıklar dahilinde. Bunu yaparken yorumu güncellemeyi unutmamız da oldukça olası. O yüzden bu detayı yorumlara yazmak mantıklı değil. Yorumlarda uygulama detaylarından bahsetmek kod/yorum tutarsızlığına bir davetiyedir.

/**
 * Kitaplardan oluşan bir dizi alır,
 * bu kitapları tek tek ekler.
 * Eklediği her kitap, listenin
 * sonuna eklenir.
 */
public static function pushAll(array $books): void;

Üçüncü hata, apaçık ortada olanı tekrar etmek. $books argümanını tanımlarken, bunun bir array olduğunu zaten belirttik. Yorumlarda zaten açıkça belli olan bir şeyi tekrar etmeye gerek yok.

/**
 * Kitapları tek tek ekler.
 * Eklediği her kitap, listenin
 * sonuna eklenir.
 */
public static function pushAll(array $books): void;

Dördündü hata, yorumun gerekenden fazla uzun olması. Evet, yorumun aslında kısa göründüğünün farkındayım; fakat çok daha kısa olabilir. Yorum ne kadar kısaysa, onu güncel tutmak da o kadar kolay olur.

/**
 * Kitapları listenin sonuna ekler.
 */
public static function pushAll(array $books): void;

Çok güzel. Yorumumuzu tek satıra kadar düşürdük. Şimdi, bir sonraki fonksiyonumuza bakalım:

/**
 * Listenin sonuna bir kitap ekler.
 */
public static function push(Book $book): void;

Fark ettiniz mi? 🙂 push() fonksiyonunda kitabın listenin sona ekleneceği zaten yazılmış. pushAll() bu fonksiyonun bir varyasyonu olduğu için, bu bilgiyi tekrar etmemize gerek yok. Tek yapmamız gereken, push() fonksiyonuna gönderme yapmak:

/**
 * @see push()
 */
public static function pushAll(array $books): void;

Öte yandan, aslında push() fonksiyonunun da yoruma ihtiyacı yok. Çünkü push terimi yazılımcılar tarafından bilinen bir terim ve bu terim zaten bir elemanı listenin sonuna eklemesiyle bilinir. Ama biz örneğimiz gereği bu yorumu yerinde bırakıp sonraki fonksiyonumuza geçelim:

/**
 * Sondaki kitabı döndürür. Fakat bunu yapabilmesi için
 * önce push() metoduyla bir kitap eklemeniz gerekir.
 * Evet, sana diyorum. Kitap eklemeden kitap almayı
 * beklemiyordun değil mi? :-) Hadi sana bir de kolaylık
 * yaptım, pushAll() diye bir fonksiyon ekledim. Koyacak
 * birden fazla kitabın varsa tek tek uğraşmazsın. ;-)
 */
public static function pop(): Book;

pop terimi de aynı push gibi bilinen bir terim. Listenin sonundaki elemanı döndürür ve bu elemanı listeden siler. Fakat bu fonksiyonun yorumundaki tek ve büyük hatayı görebiliyor musunuz? 6 satır yorum yazmışım ama ilk cümle dışında bana yararı olabilecek hiçbir şey eklememişim. Abuk sabuk yorumlar yazmak, okuyucuyu asıl odaklanması gerekenden uzaklaştırır.

/**
 * Sondaki kitabı döndürür.
 */
public static function pop(): Book;

Şimdi sınıfımızın (class) son hâline bakalım ve düzelttiğimiz hataları tekrar sıralayalım:

<?php

abstract class Book // Kitap
{
   /**
    * @see push()
    */
   public static function pushAll(array $books): void;

   /**
    * Sona bir kitap ekler.
    */
   public static function push(Book $book): void;

   /**
    * Sondaki kitabı döndürür.
    */
   public static function pop(): Book;
}

Sınıfımızın oldukça kısaldı; böylece hem daha anlaşılabilir hâle geldi, hem de olası güncellemelerimiz kolaylaştı.

Hataları düzeltirken kullandığımız bilgiler:

  1. Yorumlarda doğru terimleri kullanmalıyız.
  2. Yorumlarda uygulama detaylarından bahsetmek kod/yorum tutarsızlığına bir davetiyedir.
  3. Yorumlarda zaten açıkça belli olan bir şeyi tekrar etmeye gerek yok.
  4. Yorum ne kadar kısaysa, onu güncel tutmak da o kadar kolay olur.
  5. Abuk sabuk yorumlar yazmak, okuyucuyu asıl odaklanması gerekenden uzaklaştırır.

Yorum Gönderin

Bir Cevap Yazın

%d blogcu bunu beğendi: