Yalnızca Kodun Söyleyemediklerini Yorumlayın

Teori ve pratik arasındaki fark pratikte teoride olduğundan daha fazladır, kesinlikle yorumlar için geçerli olan bir gözlem. Teoride, kodu yorumlamanın genel fikri kulağa değerli bir fikir gibi geliyor: Okuyucuya neler olup bittiğine dair bir ayrıntı, bir açıklama sunun. Yardımcı olmaktan daha yararlı ne olabilir? Bununla birlikte, pratikte, yorumlar genellikle bir felaket haline gelir. Diğer yazı türlerinde olduğu gibi, iyi yorumlar yazma becerisi vardır. Becerinin çoğu, onları ne zaman yazmayacağınızı bilmektir.

Kod yanlış oluşturulduğunda, derleyiciler, yorumlayıcılar ve diğer araçlar kesinlikle itiraz edeceklerdir. Kod bir şekilde işlevsel olarak yanlışsa, incelemeler, statik analizler, testler ve üretim ortamındaki günlük kullanım çoğu hatayı giderecektir. Ama ya yorumlar? Elements of Programming Style'da Kernighan ve Plauger, "bir yorum yanlışsa, sıfır (veya negatif) değerdedir" demişlerdir. Yine de bu tür yorumlar genellikle kodlama hatalarının asla yapamayacağı şekilde bir kod tabanında çöp olur ve hayatta kalır. Sürekli bir dikkat dağınıklığı ve yanlış bilgi kaynağı, bir programcının düşüncesinde ince ama sürekli bir sürükleme sağlarlar.

Teknik olarak yanlış olmayan, ancak koda değer katmayan yorumlara ne dersiniz? Bu tür yorumlar gürültüdür. Kodu papağan gibi tekrar eden yorumlar okuyucuya ekstra bir şey sunmaz, bir şeyi kodda ve tekrar doğal dilde belirtmek, onu daha doğru veya daha gerçek yapmaz. Yorumlanan kod yürütülebilir kod değildir, bu nedenle okuyucu veya çalışma zamanı için yararlı bir etkisi yoktur. Ayrıca çok çabuk bayatlar. Sürümle ilgili yorumlar ve yorum yapılan kod, sürüm oluşturma ve geçmişle ilgili soruları ele almaya çalışır. Bu sorular, sürüm kontrol araçları tarafından zaten (çok daha etkili bir şekilde) yanıtlanmıştır.

Bir kod tabanında gürültülü yorumların ve yanlış yorumların yaygınlığı, programcıları tüm yorumları atlayarak veya onları gizlemek için aktif önlemler alarak görmezden gelmeye teşvik eder. Programcılar beceriklidir ve hasar olarak algılanan her şeyin etrafından dolaşırlar: yorumları yukarı katlamak; yorumların ve arka planın aynı renkte olması için renk şemasını değiştirme; yorumları filtrelemek için komut dosyası. Bir kod tabanını programcı yaratıcılığının bu tür yanlış uygulamalarından kurtarmak ve gerçek değeri olan herhangi bir yorumu gözden kaçırma riskini azaltmak için, yorumlara kodmuş gibi davranılmalıdır. Her yorum okuyucu için bir miktar değer katmalıdır, aksi takdirde kaldırılması veya yeniden yazılması israftır.

O halde değer olarak nitelenen nedir? Yorumlar, kodun söylemediği ve söyleyemeyeceği bir şey söylemelidir. Bir kod parçasının zaten ne söylemesi gerektiğini açıklayan bir yorum, kodun kendisi için konuşması için kod yapısını veya kodlama kurallarını değiştirmeye yönelik bir davettir. Zayıf yöntem veya sınıf adlarını telafi etmek yerine, bunları yeniden adlandırın. Uzun işlevlerdeki bölümleri yorumlamak yerine, adları önceki bölümlerin amacını yakalayan daha küçük işlevleri çıkarın. Kod aracılığıyla mümkün olduğunca çok ifade etmeye çalışın. Kodda ifade edebileceğiniz ile toplamda ifade etmek istediğiniz şey arasındaki herhangi bir eksiklik, faydalı bir yorum için mantıklı bir aday haline gelir. Kodun söylemediklerini değil, söyleyemediklerini yorumlayın.

Kevlin Henney Tarafından