İyi isimlendirme: Temiz kodun en ucuz ve en etkili kuralı

Programlamanın en zor iki işinden birinin "bir şeylere isim vermek" olduğu söylenir. Şaka gibi dursa da doğrudur. İsim seçmek, o şeyin ne olduğunu ve ne yaptığını gerçekten anlamayı gerektirir. Anlamadığınız bir şeye iyi bir isim veremezsiniz.

Bunun tersi de geçerli: Kötü isimler, kodu okuyan herkesi o anlamı yeniden çıkarmaya zorlar. Her seferinde.

Kötü isimlerin bedeli

function process($data) {
    $tmp = [];
    foreach ($data as $d) {
        if ($d['s'] == 2 && $d['t'] > time() - 86400 * 30) {
            $tmp[] = $d['a'] * 1.2;
        }
    }
    return array_sum($tmp);
}

Bu fonksiyon ne yapıyor? Okuyabilirsiniz, ama anlamak için her satırı çözmeniz gerekir. s neyin durumu? 2 ne demek? a ne? 1.2 nereden geliyor?

Aynı kod, iyi isimlerle:

const DURUM_TAMAMLANDI = 2;
const KDV_CARPANI = 1.20;

function sonOtuzGununKdvDahilCirosu(array $siparisler): float
{
    $otuzGunOnce = time() - 30 * 86400;
    $ciro = 0.0;

    foreach ($siparisler as $siparis) {
        $tamamlandi = $siparis['durum'] === DURUM_TAMAMLANDI;
        $sonOtuzGunde = $siparis['tarih'] > $otuzGunOnce;

        if ($tamamlandi && $sonOtuzGunde) {
            $ciro += $siparis['tutar'] * KDV_CARPANI;
        }
    }
    return $ciro;
}

Mantık hiç değişmedi. Ama artık kod kendini anlatıyor. Bir yorum satırına bile ihtiyaç yok.

Pratik kurallar

1. İsim, "ne" olduğunu anlatsın, "nasıl" saklandığını değil

Kötü:  $kullaniciDizisi, $strAd, $intYas
İyi:   $kullanicilar, $ad, $yas

Türü ismin içine yazmak (Macar notasyonu), modern editörlerin ve tür bildirimlerinin olduğu bir dünyada gereksiz tekrardır. Tür değiştiğinde isim yalan söylemeye başlar.

2. Anlamsız genel isimlerden kaçının

$data, $info, $tmp, $obj, $result, $value, $item... Bu isimler neredeyse her şey olabilir. Yani hiçbir şey anlatmaz. Ne tür bir veri? Hangi sonuç?

Kötü:  $result = $db->query(...);
İyi:   $bekleyenSiparisler = $db->query(...);

Çok kısa ömürlü döngü değişkenleri bir istisnadır. Üç satırlık bir döngüde $i ya da bir map içinde $u gayet okunaklıdır. Kural kabaca şöyle: Değişkenin kullanıldığı alan ne kadar genişse, ismi o kadar açıklayıcı olmalı.

3. Fonksiyon isimleri eylem, değişken ve sınıf isimleri nesne

Fonksiyon:  hesapla(), gonder(), siparisOlustur(), kullaniciyiBul()
Değişken:   $siparis, $toplamTutar, $musteriEposta
Sınıf:      Siparis, FaturaOlusturucu, OdemeServisi

Doğru ya da yanlış döndüren fonksiyonlar ve değişkenler bir soru gibi okunmalı:

$aktifMi, $odendi, $silinebilir, kullaniciYoneticiMi(), stoktaVarMi()

if ($odendi) cümle gibi okunur. if ($odemeDurumu) ise okuyanı durup düşünmeye zorlar: Durum ne?

4. Sihirli sayılara isim verin

86400, 2, 1.2, 0.18, 3600 gibi sayılar kodun içinde yalnız başına durduğunda anlamları kaybolur. Bir sabite isim verin:

const BIR_GUN_SANIYE = 86400;
const MAKSIMUM_GIRIS_DENEMESI = 5;

Ek bir faydası da var: KDV oranı değiştiğinde, kodun on farklı yerindeki 1.2 değerlerini aramak yerine tek bir satırı değiştirirsiniz.

5. Tutarlı olun

Aynı kavram için projede tek bir kelime kullanın. Bir yerde getir, başka yerde al, bir başka yerde bul kullanmak, okuyanı aralarında bir fark olup olmadığını düşünmeye iter:

Tutarsız:  kullaniciGetir(), siparisAl(), urunBul(), faturaCek()
Tutarlı:   kullaniciGetir(), siparisGetir(), urunGetir(), faturaGetir()

Bir fark varsa, örneğin bul bulunamazsa null döndürüyor, getir ise hata fırlatıyorsa, bu ayrımı bilinçli olarak kullanın ve her yerde aynı şekilde uygulayın.

6. Kısaltmalardan kaçının

$mstr, $adrs, $hsp, calcTtl()... Yazarken birkaç harf kazandırır, okurken her seferinde zaman kaybettirir. Herkesin bildiği kısaltmalar (id, url, html, kdv) bir istisnadır.

7. Olumsuz isimlerden kaçının

Kötü:  if (!$aktifDegil)
İyi:   if ($aktif)

Çift olumsuzluk, okuyanın kafasında gereksiz bir mantık işlemi yaptırır.

8. Dil seçin ve ona sadık kalın

Türkçe mi, İngilizce mi? Bu bir ekip kararıdır. Uluslararası bir ekip ya da açık kaynak proje için İngilizce, yerel bir ekip ve iş kurallarının yoğun olduğu bir proje için Türkçe isimler mantıklı olabilir. Önemli olan karıştırmamaktır: getMusteriAdresi() gibi yarı Türkçe yarı İngilizce isimler okunabilirliği düşürür.

Türkçe isim kullanıyorsanız, değişken isimlerinde ç, ğ, ı, ö, ş, ü gibi karakterleri kullanmayın. Pek çok dil izin verse de araçlarda, klavye düzenlerinde ve ekip arkadaşlarının ortamlarında sorun çıkarabilir.

Yeniden adlandırmaktan korkmayın

İlk seçtiğiniz isim çoğu zaman en iyisi değildir; çünkü kodu yazarken problemi henüz tam anlamamışsınızdır. Daha iyi bir isim aklınıza geldiğinde değiştirin. Modern editörlerdeki "yeniden adlandır" (rename) özelliği, bir ismi bütün projede güvenle değiştirir. Testleriniz varsa bu işlem neredeyse risksizdir.

İyi isimlendirme ek bir araç, kütüphane ya da süreç gerektirmez. Yalnızca birkaç saniye daha düşünmeyi gerektirir. Bu birkaç saniyelik yatırım, kodu okuyan herkese, en çok da altı ay sonraki size, saatler kazandırır.