Yorumlar 'Ne'yi de Açıklamalı mı?

Yazılım dünyasında yaygın bir inanış, kod yorumlarının "neden" yapıldığını açıklaması gerektiği, "ne" yapıldığını değil. Ancak bu makale, bu kurala meydan okuyarak yorumların "ne"yi de açıklamasının faydalı olabileceğini savunuyor. Yazar, w = 10 gibi belirsiz değişken tanımlamalarının, weight = 10 gibi açıklayıcı isimlerle değiştirilmesi gerektiğini kabul etmekle birlikte, her zaman bu kadar basit olmadığını belirtiyor. Kodun kendisi yeterince açık olmadığında veya kısa değişken isimleri bağlam dışına çıktığında (örneğin, w'nin daha sonra width yerine weight olduğunu hatırlamak için geri dönmek gerektiğinde), "ne"yi açıklayan yorumlar, geliştiricinin bağlam değiştirmesini engelleyebilir ve yanlış varsayımların önüne geçebilir.

Makale ayrıca, "neden" yorumlarının önemini de vurguluyor ve bu bilgiyi commit mesajlarına veya testlere taşımak yerine kodun yanında tutmanın neden daha iyi olduğunu açıklıyor. Örneğin, belirli bir kütüphane hatası nedeniyle bir fonksiyonun iki kez çağrıldığını açıklayan bir yorumun, commit geçmişinde aranmasının zor ve zaman alıcı olabileceği belirtiliyor. Git blame gibi araçların bile kodun yeniden biçimlendirilmesi veya taşınması gibi durumlarda yetersiz kalabileceği, bu durumun da bağlam değiştirmeye ve potansiyel olarak tehlikeli varsayımlara yol açabileceği ifade ediliyor.

Temel argüman, ister kodun kendisi, ister yorumlar, ister commit mesajları olsun, bilginin aranmasının her zaman bir maliyeti olduğudur. En iyi ihtimalle, bu bir bağlam değişikliğidir ve sorunu anlamaktan zaman çalar; en kötü ihtimalle ise bilgiye bakılmaz ve yanlış, tehlikeli varsayımlar yapılır. Bu nedenle, bilginin ihtiyaç duyulduğu yerde, yani kodun hemen yanında tutulması, ister açıklayıcı kod ister yorumlar aracılığıyla olsun, daha verimlidir. Hatta bazen aşırı açıklayıcı kod bile kendi içinde bağlam değişikliklerine yol açabilir, bu da yorumların değerini artırır.