Temiz Kod: İsimlendirme, Fonksiyon Boyutu ve Yorumlar

Kod bir kez yazılır, defalarca okunur. Bu yüzden okunabilirlik estetik bir tercih değil, doğrudan bakım maliyetini belirleyen bir özelliktir. Altı ay sonra aynı dosyaya bakan kişi, kodun ne yaptığını anlamak için ne kadar zaman harcıyorsa maliyet o kadar yüksektir.

Aşağıdaki kurallar soyut ilkeler değil, günlük kod incelemesinde doğrudan uygulanabilecek ölçütlerdir.

İsimlendirme

İyi bir isim, değişkenin ne tuttuğunu ya da fonksiyonun ne yaptığını açıklamadan anlatır. Kısaltma ve genel amaçlı sözcükler bu bilgiyi siler:

// belirsiz
$d = getData($x);
foreach ($d as $i) { islem($i); }

// açık
$bekleyenSiparisler = bekleyenSiparisleriGetir($magazaId);
foreach ($bekleyenSiparisler as $siparis) { hazirla($siparis); }

Boole değerler soru biçiminde adlandırıldığında koşul satırı doğal okunur: $aktifMi, $odemeTamamlandi. Fonksiyon adları ise eylem bildirir ve dönüş değeriyle uyumlu olur; getir ile başlayan bir fonksiyonun kayıt silmesi beklenmez.

İsimlendirmede tutarlılık, doğruluk kadar önemlidir. Aynı kavram için bazı yerlerde kullanici, bazı yerlerde uye kullanılması, okuyanı bunların farklı şeyler olup olmadığını düşünmeye zorlar.

Fonksiyon boyutu ve tek sorumluluk

Fonksiyonun uzunluğu tek başına ölçüt değildir. Daha güvenilir işaret, fonksiyonun ne yaptığının tek cümleyle anlatılamamasıdır. Anlatırken ve bağlacı kullanılıyorsa, orada iki iş vardır.

İkinci işaret, farklı soyutlama seviyelerinin aynı fonksiyonda karışmasıdır. Bir satırda iş kuralı, bir sonraki satırda dize birleştirme yapılıyorsa okuyan kişi sürekli seviye değiştirmek zorunda kalır.

Erken dönüş ve iç içe koşullar

İç içe geçmiş koşullar, okuyan kişinin aynı anda birden fazla durumu aklında tutmasını gerektirir. Geçersiz durumları başta eleyip çıkmak, ana akışı girintisiz bırakır:

// iç içe
function odeme(array $siparis): bool
{
    if ($siparis['aktif']) {
        if ($siparis['tutar'] > 0) {
            if (!$siparis['odendi']) {
                return tahsilEt($siparis);
            }
        }
    }

    return false;
}

// erken dönüş
function odeme(array $siparis): bool
{
    if (!$siparis['aktif']) { return false; }
    if ($siparis['tutar'] <= 0) { return false; }
    if ($siparis['odendi']) { return false; }

    return tahsilEt($siparis);
}

Yorum satırları

Yorum, kodun ne yaptığını değil neden öyle yaptığını anlatmalıdır. Ne yaptığını anlatan yorumlar kod değiştiğinde güncellenmez ve kısa sürede yanıltıcı hale gelir:

// gereksiz: kod zaten bunu söylüyor
$toplam = $toplam + $kdv; // kdv ekle

// değerli: nedenini kod söyleyemez
// Tedarikçi API'si 2 saniyeden uzun
// isteklerde bağlantıyı düşürüyor, bu yüzden sayfa boyutu 50 ile sınırlı.
$sayfaBoyutu = 50;

Geçici çözümlerin yanına nedeni ve mümkünse kaynağı yazılmalıdır. Bu not, sonradan bakan kişinin çözümü gereksiz sanıp kaldırmasını engeller.

Ölü kod ve yoruma alınmış bloklar

Yorum satırına alınmış kod blokları, sürüm kontrolü kullanılan bir projede hiçbir işe yaramaz. Eski hâle ihtiyaç duyulduğunda geçmişten alınabilir; dosyada bırakıldığında ise okuyan kişiyi hangisinin geçerli olduğunu düşünmeye zorlar.

Aynı şey çağrılmayan fonksiyonlar ve kullanılmayan değişkenler için de geçerlidir. Statik analiz araçları bunları otomatik işaretler ve temizlik sürekli hale getirilebilir.

Sihirli değerler ve tekrar

Kodun içine dağılmış sabit sayılar ve metinler, değiştiği gün birden fazla yerde arama yapmayı gerektirir. Bu değerler adlandırılmış sabitlere alındığında hem anlamları görünür olur hem de tek noktadan değişir.

// sihirli değer
if ($kullanici['rol'] === 3) { /* ... */ }
if ($tutar > 5000) { /* ... */ }

// adlandırılmış
enum Rol: int
{
    case Yonetici = 1;
    case Editor = 2;
    case Uye = 3;
}

private const ONAY_GEREKEN_TUTAR = 5000;

Tekrar eden kod parçaları için de aynı mantık geçerlidir. Ancak benzer görünen her blok aynı değildir; farklı nedenlerle değişecek iki parçayı birleştirmek, ileride ayrıştırılması gereken bir bağ kurar.

Ölçüyü kod incelemesine taşımak

Bu kuralların kalıcı olması, kişisel disipline değil sürece bağlıdır. Biçim denetleyicisi ve statik analiz araçları sürekli tümleştirme akışında çalıştırıldığında, tartışma konusu olmaktan çıkar.

Kod incelemesinde ise biçim yerine yapıya odaklanmak gerekir. Girinti ve boşluk araç tarafından düzeltilir; incelemede sorulacak soru, kodun altı ay sonra anlaşılabilir olup olmadığıdır.

Ölçülebilir bir gösterge de kullanılabilir. Bir dosyada değişiklik yapıldığında kaç farklı dosyanın da değişmek zorunda kaldığı, bağların ne kadar sıkı olduğunu gösterir. Bu sayı zamanla artıyorsa, sorun biçimde değil yapıdadır.

Kontrol listesi

• İsimler kısaltma içermez ve ne olduğunu açıklar.
• Aynı kavram her yerde aynı sözcükle anılır.
• Fonksiyonun işi tek cümleyle anlatılabilir.
• Geçersiz durumlar başta elenir, ana akış girintisiz kalır.
• Yorumlar nedeni anlatır.
• Yoruma alınmış kod ve ölü kod dosyada bırakılmaz.

İlgili yazılar

• OOP: Sınıf, Arayüz ve Soyutlama
• PHP Fonksiyonlar: Parametre, Dönüş Tipi ve Kapsam