Neden Olmadı Yorumları

• Neden "neden olmadı" yorumları? Neden "yorum yok" değil
  • “Neden ‘neden işe yaramadığını’ açıklayan yorumlar bırakmıyorsunuz? Sormak istediğim şey ‘neden yorum eklemediğiniz’ değil.”

Neden Olmadı Yorumları

• Kod, yapılandırılmış bir makine diliyle yazılır; yorumlar ise ifade gücü yüksek insan diliyle yazılır
• Amaç, "ne"yi yorumlamamak; bunun yerine mümkün olduğunca fazla bilgiyi tanımlayıcılara yerleştirmektir
• Son dönemde, "neden"in de yorumlara değil LongFunctionNames ya da test vakası adlarına konulması gerektiği savunuluyor
• "Kendini belgeleyen" kod tabanları, tanımlayıcılar aracılığıyla dokümantasyon ekler

Yakın tarihli bir örnek

• Logic for Programmers kitabından bir örnek
• epub derlemesinin matematik sembollerini (\forall) karaktere (∀) dönüştürememesi sorunu ortaya çıktı
• Matematik dizelerindeki token'ları Unicode ile elle değiştiren bir betik yazıldı
• Bu, 16 matematik sembolünün her biri için ayrı ayrı değiştirme yapacak şekilde yazıldı; ancak bu verimsiz bir yöntem
• Basit bir yorum eklenerek çözüldü
  • "Her dize için 16 kez dönüyor, ancak şu an kitapta yalnızca 25 matematik dizesi var ve bunların çoğu 5 karakterden kısa, bu yüzden yine de yeterince hızlı"

Neden yorum eklenmeli

• Yavaş kod sorun çıkarmasa bile neden yorum eklenmesi gerektiği
• Kod gelecekte sorun yaratabilir
• Yorumlar, yapılan trade-off'un farkında olunduğunu gösterir
• Projeye daha sonra geri dönüldüğünde neden yavaş kod yazıldığını anlamayı sağlar

Kendini belgeleyen kod neden mümkün değil

• RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs gibi uzun işlev adları trade-off'u açıklamaz
• İşlev ve değişken tanımlayıcıları yalnızca tek bir bilgi türünü taşıyabilir
• Yorumları testlerle değiştirmek de mümkün değildir
• Kendini belgeleyen yapı, kodun ne yaptığını açıklar; negatif bilgi ise kodun ne yapmadığını açıklar

Bültenin sonundaki spekülasyon

• "Neden işe yaramadığını" anlatan yorumların karşı-olgusal örnekler olarak düşünülemeyeceği merak ediliyor
• İnsan iletişimindeki soyutlamalar kendini belgeleyen hale getirilemez mi?
• Mecazlar, belirsizlikler, etik iddialar vb. kendini belgeleyen şekilde ifade edilebilir mi?

---

GN⁺ özeti

• Bu yazı, kod yorumlarının önemini ve sınırlarını ele alıyor
• Yorumlar, koddaki trade-off'ları netleştiriyor ve gelecekteki bakım işini kolaylaştırıyor
• Kendini belgeleyen yaklaşımın sınırlarını ve yorumların gerekliliğini vurguluyor

[GN⁺]

Hacker News görüşleri

• Koda yorum eklerken çoğunlukla "neden"i ve "neden işe yaramadığını" açıklarım. Kod karmaşıksa, "ne" yaptığını kısaca açıklamak da faydalıdır

  • Zorunlu yorumlar verimsizdir ve her fonksiyona yorum yazmak zaman kaybıdır
  • Araçların otomatik olarak eklediği yorumlar da verimsizdir

• Junior mühendisler kodun ne yaptığını açıklayan yorumlar yazar, orta seviye mühendisler neden böyle yazıldığını açıklar, senior mühendisler ise neden başka türlü yazılmadığını açıklar

• Bakım yapacak kişiler için bir yorum şablonu kullanırım

  • "Bu kod <neden> yüzünden böyle yazıldı. Değiştirmeye çalışıp bunun bir hata olduğunu fark ederseniz, sıradaki kişi için sayacı artırın: total_hours_wasted_here = n"

• Kodda şaşırtıcı olan yerlere yorum eklemek önemlidir

  • Kodun daha sonra anlaşılacağından emin olmadığımda, "neden işe yaramadığını" açıklayan yorumlar yazarım

• Yorumların önemini vurguluyorum; özellikle kendi kodunuzu 5, 10, 15 yıl sonra da bakımını yapmanız gerekecekse çok faydalıdır

  • Mevcut kodla tutarlılığı korumak önemlidir

• "naif çözüm olmayan" yerlere yorum eklemek iyidir

  • Verimsiz kod daha sonra düzeltilirken sorunlara yol açabilir

• Uzun fonksiyon adlarına veya test case adlarına yorumu dahil etmek iyidir

  • Metot adı yeterince açık değilse yorum faydalı olur
  • Metot açıklamasında "ve" geçiyorsa, bu metot çok fazla iş yapıyor demektir

• Debug logging üzerinden, girdiler ilk tasarım kısıtlarından daha büyük olduğunda uyarı eklemek de faydalıdır

• Yorumları ve dokümantasyon yorumlarını bolca kullanmayı tercih ederim

  • Uygulamanın her aşaması için yorum yazar, kodu yazarken bu yorumları daha ayrıntılı hale getiririm
  • Tüm fonksiyonlara ve değişkenlere yorum eklemeyi tercih ederim

• Kod incelemesinde gelebilecek eleştirileri peşinen önlemek için "X yapmadım çünkü Y" şeklinde yorum yazarım