Self-explanatory kod yanılgısı, yazılım dünyasının en zararlı batıl inançlarından biri. "İyi yazılmış kod zaten kendini açıklar" sözünü çok duyduk. Bu yaklaşım, dokümantasyon yazmaktan kaçınmanın zarif bir gerekçesine dönüştü. Self-explanatory kod yanılgısının temelinde şu hata var: Kodu yazan kişi, kodu okuyan kişiyle aynı bağlamı paylaşıyor varsayılıyor. Değişken adı 'calculateTax' gayet açık görünebilir, ama hangi vergi? Hangi ülkenin kuralları? İstisnaları var mı? Bu soruları kod kendisi cevaplamıyor, cevaplamak da zorunda değil. Ama bu soruların yanıtlanması gerekiyor. Bir de şunu düşün: Kodu yazan kişi 6 ay sonra o projeye döndüğünde, kendi yazdığı 'self-explanatory' fonksiyonun ne iş yaptığını anlamak için ciddi zaman harcıyor. Çünkü o andaki bağlam, karar arkasındaki neden ve uç durumlar, zihninde artık mevcut değil. Self-explanatory kod yanılgısı özellikle tehlikeli olduğunda: İş mantığı karmaşık olduğunda, düzensiz ya da geçici bir çözüm yazıldığında ve kritik altyapı kodu söz konusu olduğunda. Bunların hepsinde yorum satırı ya da harici açıklama şart. Alternatif yaklaşım: Kod ne yaptığını gösterir, yorum neden yapıldığını açıklar. Bu ikisi birbirinin rakibi değil, tamamlayıcısı. Karmaşık kararlar için karar kaydı (decision log) tutmak da etkili bir yöntem. Self-explanatory kod yanılgısına inanmaya devam eden ekipler, bir gün başkasının ya da kendi yazdığı kodu çözmeye çalışırken saatler kaybedecek.