İster tek başınıza çalışın isterseniz bir ekip ile yazdığınız ya da başkası tarafından yazılan kodu hatırlamak ya da anlamak kolay olmayabiliyor. Daha önceden yazmış olduğunuz bir methodun ne iş yaptığını, aldığı parametrelerin tiplerinin ne olması gerektiğini ya da ne return ettiğini anlamak için gerekli işlemleri yapmadıysanız bunu anlamak ve çözmek zaman alabiliyor.

Bu sorunun çözümü için yazdığınız methodda gerekli yorum satırlarını eklemeniz gerekiyor. Her yazılım dilinin kendi için geliştirdiği çözümler mevcut. Php‘de ise bu yorum satırlarının nasıl tanımlanacağı ve kullanılacağı phpDocumentor ile belirtilmiştir. PhpDocumentor kısaca phpDoc adıylada kullanılmaktadır.

PhpDoc Kullanılmadan Yazılan Method Örneği

function sum(?array $values): ?int
{
    if (empty($values)) {
        return null;
    }
    
    $total = 0;
    foreach ($values as $value) {
        if (!is_int($value)) {
            throw new Exception("Value is not an integer!");
        }

        $total += $value;
    }

    return $total;
}

Yukarıda basit bir işlem yapan kısa bit method örneği mevcut. Örnekte dikkat ederseniz Type Declarations tanımlaması da yapılmamış. Bu methodun hangi tipde parametre aldığını, methodun hangi işlemi gerçekleştirip sonucunda hangi tipde veri return ettiğini anlayabilmeniz için bütün methodu okuyup anlamanız gerekecektir. Bu method için okumak anlamak kolayken daha uzun ve karmaşık bir methodda bu süreç daha zor olacaktır.

PhpDoc Tanımlamaları Yapılan Method Örneği

/**
 * Bu fonksiyon gelen dizi içerisindeki integer değerlerin toplamını hesaplar
 *
 * @param array|null $values Hesaplama için kullanılacak integer değer dizisi ya da null değer
 *
 * @return int|null
 *
 * @throws Exception Eğer dizi içerisinde integer olmayan değer varsa
 */
function sum(?array $values): ?int
{
    if (empty($values)) {
        return null;
    }
    
    $total = 0;
    foreach ($values as $value) {
        if (!is_int($value)) {
            throw new Exception("Value is not an integer!");
        }

        $total += $value;
    }

    return $total;
}

Yukarıdaki örnekte type declaration‘ı yapılmış ve phpDoc etiketleriyle açıklama satırları eklenmiştir. Belirtilen yorum satırlarında;

  • ‘Bu fonksiyon gelen dizi içerisindeki integer değerlerin toplamını hesaplar’ açıklaması ile methodun yaptığı iş açıklanıyor.
  • @param etiketi ile $values parametresi için sadece array ve null tipinde veri kabul edildiği açıklanıyor.
  • @return etiketi methodun sadece int ve null tipinde değer return edebileceğini açıklıyor.
  • @throws etiketi methodun hata fırlatabileceğini ve hangi durumda meydana geleceğini açıklıyor.

Burada not olarak paylaşmak istediğim bir nokta var phpDoc için de belirtilen veri tipleri method için belirtilen return ‘: ?int’ tipine göre ve parametrede belirtilen ‘?array’ tipi ne göre oluşturulmuştur.

Eğer yazdığınız method sadece belirli veri tiplerini parametre olarak alacaksa ya da belirli bir veri tipini return edecekse bunu sadece phpDoc’da tanımlamanız yetmez. Php’nin tür dayatması/type Declaration özelliğini kullanarak bu veri tiplerini belirtmeniz gerekir. Tür dayatması bulunmayan ve sadece phpDoc yorumlarında belirtilen tanımlamalar methoda beklenmeyen tipde veri gelmesini ya da return edilmesini engellemeyecektir.

En Çok Kullanılan PhpDoc Etiketleri

  • @deprecated: Terk edilmiş, kullanılmayan method, sınıf açıklaması için kullanılır
  • @param: Parametrenin adı ve veri tipinin açıklaması için kullanılır
  • @return: Return edilen değerin veri tipinin açıklaması için kullanılır
  • @throws: Fırlatılan hatalar ve açıklaması için kullanılır

PhpDocumentor’un bütün etiketleri için bu etiket listesini kontrol edebilirsiniz.

PhpDocmentor Tanımlamalarının Faydası

  • Kodun anlaşılabilirliğini arttır
  • Kodun okunabilirliğini arttırır
  • Kodun dökümante edilmesini kolaylaştırır
  • Kod yazmak için PhpStrom gibi güçlü ve profesyonel IDE kullanıyorsanız eklemiş olduğunuz phpDoc etiketleri kod yazmanız sırasında da size veri tipleri konusunda uyarma, kod tamamlama gibi kolaylıklar sağlayacaktır.

CEVAP VER

Lütfen yorumunuzu giriniz!
Lütfen isminizi buraya giriniz