Temiz Kod ile Anlaşılır Kod Aynı Şey Değildir: Yorum Satırları Asla Sorun Olmadı

Yazılım sektöründe bir dönem, koda yorum yazmanın bir geliştirici yetersizliği olduğu ve "iyi kodun kendi kendini açıklaması gerektiği" fikri popülerleşti. İdeal dünyada her dosyanın bir bakışta anlaşılması harika olurdu; fakat en kusursuz dağ yolunda bile "keskin viraj" levhası vardır. Bu levha mühendislik hatasından değil, virajın arkasını önceden görmenin imkânsız olmasından kaynaklanır. Gerçek dünyada şu üç tür kodla her zaman karşılaşırız:

Yapı gözetilmeden yazılmış kodlar: Mimari bir düzen olmadan aceleyle yazıldığı için kimsenin anlayamadığı karmaşık kodlar.
Zarif ama aşırı karmaşık kodlar: Çok temiz yazılmış olsa bile çözdüğü problem doğası gereği saatlerce odaklanmayı gerektiren algoritmalar.
Görünmeyen bir amaca hizmet eden kodlar: Dışarıdan bakıldığında gereksiz veya basit görünen, ancak sistemin çökmesini engelleyen kritik bir nedenden ötürü var olan satırlar.

Bazı Kodlar Kendini Açıklayamaz

Örneğin C# dilinde kaynak üretim (source-generated regex) kullanan modern ve temiz bir uçuş numarası doğrulama sınıfı düşünelim:

public static partial class FlightNumbers
{
    [GeneratedRegex(@"^([A-Z]{2}|[A-Z]\d|\d[A-Z])(\d{1,4})([A-Z]?)$")]
    private static partial Regex FlightNumber();

    public static bool IsValid(string input) =>
        FlightNumber().IsMatch(input.Replace(" ", "").ToUpperInvariant());
}

Kod temizdir, ancak şu test girdilerinden hangilerinin geçerli olduğunu bir bakışta söyleyebilir misiniz?

FlightNumbers.IsValid("BA123");
FlightNumbers.IsValid("U21234");
FlightNumbers.IsValid("9W5A");
FlightNumbers.IsValid("99123");

Havacılık alan bilgisine (domain knowledge) veya ileri düzey regex uzmanlığına sahip değilseniz bu kuralı anlamak zordur. Testler ve dokümanlar reklamdaki hamburger gibidir; kriz anında kutunun içi boş çıkabilir. Oysa fonksiyonun üzerine eklenecek şu açıklama zihinsel sürtünmeyi anında yok eder:

IATA uçuş numarası formatı (örneğin "BA123", "U21234", "9W5A").
Havayolu kodu 2 karakterdir: iki harf veya harf-rakam kombinasyonu (örneğin U2 = easyJet).
Ardından 1-4 haneli uçuş numarası ve opsiyonel operasyonel son ek harfi gelir.
Yalnızca büyük harf ve boşluksuz: eşleşme öncesinde girdi normalize edilir.

Kod "Ne" Yaptığını Bilir, Yalnızca Siz "Neden"ini Bilirsiniz

Kod, algoritmanın "ne" yaptığını açıklar; ancak o kararın ardındaki iş mantığını, yasal zorunlulukları veya teknik kısıtları yalnızca siz bilirsiniz. Bu nedenler kod satırlarına gömülü değildir.

"Commit Mesajına Yaz Geç" Yanılgısı

"Detayı commit mesajına yazın" tavsiyesi pratikte çalışmaz. Gece yarısı canlı ortamda çıkan bir hatayı çözerken kimse git geçmişinde dedektiflik yapmak istemez; bağlam doğrudan kodun yanında olmalıdır.

Olabilecek En Kötü Şey Ne?

Neden yazıldığı bilinmeyen temiz kodlar, diğer geliştiriciler tarafından "gereksiz" görülerek silinir veya yanlış refactor edilir; bu da doğrudan prodüksiyon kesintilerine yol açar.

Yorum Nasıl Yazılmaz?

Aşikar olanı tekrarlayan (örneğin count++ // sayacı bir artır) yorumlar sadece görsel kirliliktir. İyi bir yorum satırı kodun ne yaptığını değil, neden o şekilde yazıldığını açıklamalıdır.

Temiz Kod Sizi Yolun Yarısına Getirir

Temiz kod (clean code) okunabilirlik ve biçimlendirme ile ilgilidir, sizi yolun yarısına taşır. Anlaşılır kod (clear code) ise niyet ve iş mantığını görünür kılar. Yorum satırları bir başarısızlık değil, ekip içi iletişimin en etkili aracıdır.

Orijinal kaynağa buradan ulaşabilirsiniz.