"İyi kod kendini açıklar" cümlesi, yazılım dünyasının en çok tekrarlanan ve en çok yanlış anlaşılan önermelerinden biridir. Kod yorumu önemi tartışılırken bu önerme sıklıkla kalkan olarak kullanılır. Oysa öz-açıklayan kod ile yorumsuz kod arasında derin bir fark vardır. Kod yorumu önemi, pratikte şu soruyla test edilebilir: Altı ay sonra bu koda bakan biri, neden bu seçimin yapıldığını anlayabilir mi? Ne yapıldığını anlamak çoğu zaman mümkündür; zaten iyi isimlendirme, mantıklı yapı ve temiz fonksiyon sınırları bunu sağlar. Ama neden bu yolun tercih edildiğini, hangi alternatifin neden reddedildiğini, hangi kısıtlamanın bu yapıyı zorladığını anlamak; ancak yorumlarla mümkün olur. "Kod kendini açıklar" yorumculuğu, genellikle şu anda kodu yazan kişinin bakış açısını yansıtır. O kişi tüm bağlamı biliyor; kısıtlamaları, tartışmaları, başarısız denemeleri. Ama bu bağlam, koda yazılmadıkça kaybolur. Altı ay sonra aynı geliştirici bile o bağlamı hatırlamayabilir. Kod yorumu yazmamayı meşrulaştırmak için öne sürülen başka bir argüman da "yorumlar eskir ve yanıltıcı olur" iddiasıdır. Bu gerçek bir risk, ancak mevcut yorumları güncel tutmayı ihmal etmekle başlayan bir sorun. Eskiyen yorum sorunu, yorumların tümden kaldırılması için değil, onların bakımının disiplinli yapılması için bir çağrıdır. Kod yorumu önemi en çok şu bağlamlarda ortaya çıkar: Karmaşık algoritmalarda neden bu yaklaşımın seçildiği; geçici çözümlerde (hack) neden bu yola gidildiği ve ne zaman geri dönülmesi gerektiği; harici sistem kısıtlamalarını yansıtan kısımlar; ve performans optimizasyonu yapılan alanlarda orijinal sürümün neden değiştirildiği. "Yorum yazmaya gerek yok, test yaz" görüşü de bu tartışmada sık duyulur. Testler kodun davranışını belgeler; yorumlar ise niyeti. Bu ikisi birbirinin yerine geçmez, tamamlayıcıdır. Profesyonel geliştiriciler, yorumsuz kodu kaliteli saymazlar. Kodu ileride okuyacak olan kişiye, ki bu çoğunlukla kendileridir, saygı göstermek, yorumla başlar.