PHPDoc Yorumları: @param ve @return Ne Zaman Yazılır?

PHP'de yorum satırı çoğu zaman kodu açıklamak için açılır; fakat açıklama her satırda ne olduğunu tekrar ediyorsa kısa sürede bakım yüküne dönüşür. PHPDoc daha işe yarar bir noktada devreye girer: fonksiyonun sözleşmesini, beklediği veriyi ve döndürdüğü değeri kodu okuyan kişiye ve statik analiz araçlarına aktarır.

Yerel tür bildirimi varken PHPDoc ne ekler?

PHP'nin yerel tür bildirimleri parametre ve dönüş türlerini çalışma zamanında da denetleyebilir. PHPDoc ise yerel sözdiziminin tek başına anlatamadığı ayrıntılarda kullanışlıdır: belirli anahtarlara sahip bir dizi, bir listenin eleman türü veya bir parametrenin hangi koşulda null olabileceği gibi.

/**
 * @param list<int> $postIds Pozitif yazı kimlikleri
 * @return array<int, string> Kimlikten başlığa eşleme
 */
function loadTitles(array $postIds): array
{
    // ...
}

Burada PHP motoru list<int> bilgisini kendiliğinden doğrulamaz. Bu ifade, PHPStan veya Psalm gibi analiz araçlarının ve kod incelemesi yapan kişinin anlayacağı ek bir sözleşmedir. Fonksiyon gerçekten bu sözleşmeye uymuyorsa etiket eklemek kodu daha güvenli yapmaz; yalnızca yanlış bir beklenti üretir.

Etiketleri ne zaman yazmalı?

@param ve @return, türün veya anlamın imzadan açıkça çıkarılamadığı yerde değer katar. Dönüş değeri birden fazla biçim alıyorsa bunu açıklamak, harici bir formatın alanlarını belgelemek ya da genel bir dizinin beklenen şeklini belirtmek iyi bir örnektir. Öte yandan function save(User $user): bool imzasında aynı bilgiyi sözcüğü sözcüğüne tekrarlamak genellikle gereksizdir.

@param metninde yalnızca türü değil, çağıranın sorumluluğunu da yazın: kimlik listesi boş olabilir mi, tarih hangi saat diliminde bekleniyor, başarısızlıkta istisna mı dönüyor? Bu açıklamalar iş kuralını anlatmalı; fonksiyon gövdesindeki her adımı kopyalamamalıdır.

Belgeyi kodla birlikte doğrulayın

Bir parametrenin türünü değiştirdiğinizde PHPDoc'u da aynı değişiklik içinde güncelleyin. Analiz aracının raporunda eski tür hala görünüyorsa yorum koddan kopmuş demektir. phpDocumentor'un PHPDoc temel sözdizimi ve DocBlock açıklaması etiket formatı için başvurulacak kaynaklardır.

Genel yorum ile DocBlock arasındaki farkı örneklerle görmek için PHP yorum satırları ve kullanım amaçları yazısına da bakabilirsiniz. Buradaki ölçüt basit: açıklama çağıranın yanlış kullanımını önlüyor veya analiz aracına yerel türlerden fazlasını söylüyorsa kalsın; yalnızca satırı Türkçeye çeviriyorsa silin.