Koda yorum yazmak mı yoksa yazmamak mı?

Merhabalar herkese,

Yıllardır tartışmasını yaptığım ve kod içerisindeki yorum satırları yani code comment konusunda fikirlerimi tecrübelerime dayanarak paylaşmak istiyorum.

Kısa Özet: Kod içerisine yorum yazmayın!

Eğer neden böyle düşündüğümü merak ediyorsanız yazının devamında detaylı açıklayacağım.

Her developer temiz kod yazmak ister. Hangi developer’a sorarsanız sorun bunu söylecektir hatta üstüne SOLID, YAGNI gibi bir çok prensibin çok önemli olduğunu da ekleyecektir. O zaman sorumuzu soralım, “O kadar temiz kod yazıyorsan, burada ne yaptığını neden açıklama ihtiyacı duydun?”. Bu sorunun cevabını tam olarak kimse veremez. Genelde bir architect’in ya da takımdan sorumlu kişiden dolayı çok büyük complexity problemi oluşur. Dolayısıyla Single prensibi uygulanamaz ve methodlar uzamaya başlar. Bu function seviyesinde de class seviyesinde de hatta service seviyesinde de aynı şekilde devam eder. Yani başlangıç olarak yanlış tasarıma bunun devamında da dolayısıyla kötü koda(bad code) yol açar.

Temel olarak şu şekilde bakalım; başka birinin yazdığı kodu yorum olmadan okuyup anlayabiliyorsa yoruma ihtiyaç yoktur. Yorum yazmanız gerekliyse çok karmaşık bir işlem yapıyordur. İyi isimlendirilmiş class, function ve property’ler yoruma ihtiyaç duymaz.

Yorum satırlarının temel sorunları

Yorum satırları ekstra bir bakım maliyeti getirir. Bir kod değiştiğinde o yorum satırlarını da değiştirilmesi gerekir. Bu da development hızını düşürür ki bu istemediğimiz bir durum.

Bir property ya da class’ın tepesine ne işe yaradığını yazıyorsak zaten iyi isimlendiremediğimiz anlamına gelir. Yani kod satırları para ile değil, uzun ve anlamlı isimler seçmek zor şeyler değil.

Yorum yazıyorsanız genel olarak kodunuz bu şekilde görünmeye başlar.

Eğer bu şekilde isimlendirirseniz yoruma gerek kalmaz ve her şeyi ismi anlatır

Örnekteki function’a çok takılmayın, kafanızda canlanması için verdiğim bir örnek. Tabi ki clean code yazabilmek için interface vb. bir çok yapı kullanıyoruz. Bu tipler ile sadece Find() şeklinde bir function’ı implicit olarak ekleyerek de aynı okunurluk seviyesine ulaşabilirsiniz.

Devam etmeden önce ilginç bir detay vermek istiyorum. Şu ana kadar öğrendiğiniz ya da gördüğünüz bir çok bilgiye ters düşen şeyler söylemiş olma ihtimalim var. Bu tip görüşler uzun süredir kod yazdığım ve comment yapılarını ne kadar uğraşırsan uğraş tam anlamıyla bakım yapamayıp daha çok üzerimize yük olarak kaldığını gördüğüm için bu düşünceler şekillenmeye başladı. Daha sonra Clean Code adlı kitabı 2. kez gözden geçirdim. Evet doğru hatırlıyorum, sadece ben değil diğer insanlar da benim gibi düşünen kişiler var.

“Eğer bir kod yorumu yazıyorsanız, ne yaptığınızı insanlara açıklamak zorunda kalmışsınız yani kendinizi ifade edememişsiniz demektir” Clean Code

Ben de bu şekilde düşünüp geliştirdiğim uygulamalar gittikçe daha temiz olmaya başladı.

Gereksiz yorumlar

Çok gördüğüm bir durum. Customer class’ında müşteri sınıfı diye yorum atmak tam anlamıyla boşa bir efor. Yazmasa da olurdu denecek bir çok kod yorumu satırı gördüm. Bir noktadan sonra sırf yazmak için yazılıyor ve üzerindeki büyü çabuk kaçıyor. Neredeyse her developer için angarya bir işe dönüştüğünden kısa kısa kelimeler yazıyorlar, zaten bu kadar kısa yazılıp anlaşılabilecek bir kod yazdıysan onu eklemesen de anlarız diye düşünüyorum.

Yukarıdaki yorum olmasa da herkes anlar diye düşünüyorum.

Bu gereksiz eforları da çıkarınca yorum satırlarına ihtiyaç baya azalmış olacaktır.

Tamamen yoruma alınmış kod satırları (commented out)

Böyle bir kullanıma ihtiyaç duyulmasını gerçekten anlayamıyorum. Bu kişiler bana göre versioning sistemlerinin ne olduğunu anlamamışlar. Sadece o kodu silip düzgün bir not ile commit’lediğinde geçmişe dönük de takip edilebilecek atomik bir iş yapmış olacaklar. Git, svn vb. sistemlerin zaten en büyük avantajı bu, araba alıp sadece dümdüz kullanıp diğer güzel özelliklerini kullanmadan dümdüz direksiyonu tutarak sürmeye benziyor.

TODO vb. yorum satırları

Önemli bir iş olup TODO yazmak, developer’ın tembelliği gibi geliyor. Eksik bir durum olduğunu farkedip bunu düzeltmemek, burası yanlış çalışmaya devam etsin demek. Bu da yaptığı işi sahiplenmeyen bir kişiye işaret ediyor. Yani sorun daha büyük bir durumun işareti oluyor. Gerçekten samimi bir anket yapsak ve “TODO comment’i yazanların kaçı fırsat bulup bu işleri tamamlıyor?” diye sorsak sonuçlar nasıl olurdu? Ben samimi bir şekilde söylemeliyim ki bugüne kadar bir kaç kere TODO yazdım ve hiç dönüp yaptığımı hatırlamıyorum. Tabi bunu huy edinmedim ve elimden geldiğince TODO gereken yerleri çözmeye çalıştım. Dolayısıyla daha az bug üreten yapılar kurulmasına yardımcı oldum. Siz aksini düşünüyorsanız, ne düşündüğünüzü bana iletin lütfen.

Kandıran kod yorumları

Evet bazı kod yorumları sizi fena şekilde kandırabilir. Bunun temel sebebi işlevi değiştiren bir kod blogundaki yorumu güncellememiş olmaları. Siz bir kod geliştirirken bu yorumları dikkate alıp işlem yaptığınızda bazen istediğiniz data gelmeyebilir ya da exception alabilirsiniz. Yukarıda da bahsettiğim bakım maliyetinden dolayı bu yorum satırları güncellenmemiş olabilir. Bu açıdan doğru çalışacağını düşündüğünüz bir kod sizi saatlerce uğraştırabilir. Bunu zaten 1–2 kere yaşasanız, kod yorumlarına güveniniz kalmıyor ve kod geliştirme süreçlerinde zaten benim dediğim konuma geliyorsunuz. Bu nokta da yorum değil function, class vb. isimlendirmelerinin önemi ortaya çıkıyor.

Burada normal bir customer class’ı var. Yorumlu falan üstelik!

Eğer biri gelip City gereksiz diyip silerse ve yorumu silmezse ve böyle bir şeye bakarsanız ne olur sizce?

Bu sorunu aşmak için Pull Request aşamasında detaylı bir yorum kontrolü yapabilirsiniz. Bu da ekstra dikkat gerektiren bir iş. Bu şekilde devam ettiğinde bir noktada gözünüzden bir durum kaçacak ve yukarıdaki döngüye girip yoruma güven sıfırlanacak.

SOLID ve yorum satırları

SOLID prensibini herkesin bildiğini düşünüyorum. Eğer bilmiyorsanız bu noktada kısaca bir araştırıp okuyup devam etmeniz sizin avantajınıza olur ki zaten çok karmaşık bir konu değil.

SOLID’e göre bir function tek bir işe yaramalı. Bu prensibi sürdürürsek, bir class’da tek bir işe yaramalı hatta bir API’de tek bir işe yaramalı. Bakınca Rest presipleri de buna uyuyor. Tam da bu noktada her şey daha mantıklı gelmeye başlıyor. Bütün prensipler, bildiğimiz bütün best practices’ler aslında SOLID’den ya inherit almış ya da onu bir şekilde kendi içerisine homojen bir şekilde dağıttığını görürüz.

SOLID’in bize dediği şeyleri yapınca kod daha temiz, daha okunaklı ve refactor edilmesi çok daha kolay olduğunu görüyoruz. Dependency Inversion ve Interface Segregation prensipleri de daha yüksek kalitede test yazabilmemizi sağlıyor. (Test yazı dizimde bunlardan detaylı şekilde bahsediyorum meraklısının dikkatine).

Interface’leri doğru şekilde bölersek,

Find()

Add()

Update()

şeklindeki methodlar sadece tek bir işe yarayan class’ımıza implicit olarak eklendiğinde, sadece customer bulan, ya da sadece customer ekleyen function’lar ortaya çıkacak. Bu noktada zaten ne bir yoruma ne de ekstra bir yapıya ihtiyaç duyacağız.

Kod yorum satırları ilginç bir şekilde işe yarar ve önemli görünüp ama bir o kadar zıttı olan bir konsept. Şu an aktif olarak yorum satırı yazdığım tek bir yer var, o da public olarak kullanılan API’lerin endpoint’leri. Bunları Swagger’la toplayıp kullanıcılara göndermek kolay oluyor. Bunun dışında da kullanmıyorum ve henüz bir sıkıntı yaşamadım.

Siz de kod yorum satırlarını kullanıyor musunuz ya da okuduğunuz bu yazı sonrası fikirleriniz değişti mi, merak ediyorum. Güzel bir tartışma konusu olur, twitter’a ya da aşağıya yorumlara beklerim.

Saygılarımla.