İyi Kod Yorumları Yazma Rehberi

• Kod yorumlarının rolü:

  • Kod yorumları, yalnızca “yazdığınız kodun ne yaptığını” açıklamanın ötesinde; tasarım kararları, trade-off’lar ve değerlendirme süreçleri gibi unsurları da belgelendirir.
  • Böylece “kodu yazan kişinin ne yaptığı ve bunu neden böyle yaptığı” açıklanmış olur.
  • Kod yorumları, geçmişte kod yazımı sırasında alınan kararların bağlamını paylaşmaya yardımcı olur.
  • Bu sayede yalnızca kodla ifade edilmesi zor olan bilgiler aktarılabilir.

• Kod yorumlarının önemi:

  • Karmaşık kodun önüne eklenen satır içi yorumlar, daha sonra bu kodu inceleyecek diğer geliştiricilerin zamanını kazandırır.
  • Proje geliştikçe, geçmişte alınan kod kararlarının bağlamını bırakmak diğer geliştiricilere yardımcı olur.
  • Kod karmaşıksa, önünde tek satırlık bir satır içi yorum bile bulunmalıdır.
  • Kod kararlarının bağlamı dahil çeşitli bilgileri yalnızca kodla aktarmanın sınırları vardır.

• İyi kod yorumu yazma yöntemleri:

  1. Kısa ve öz yazın
     • Yorumları yalnızca gerçekten gerektiğinde, gerekli temel bilgileri içerecek şekilde yazın.
       • Kod kaçınılmaz olarak karmaşıksa
       • Hassasiyeti artırmak için ayrıntı eklemeniz gerekiyorsa
       • Bağlam eksikse (ör. başka bir repository veya paketteki kod kullanılıyorsa)
     • Yorumlarda kafa karışıklığını ve belirsizliği azaltın; faydalı bağlam ve bilgi sunun.
  2. TODO/FIXME yorumlarını kullanın
     • TODO/FIXME yorumları, “kodun belirli bir bölümündeki işin tamamlanmadığını veya düzeltilmesi gerektiğini” göstermenin bir yoludur.
     • Bir fonksiyonun önüne “TODO: XX özelliği eklenmeli” gibi yazılabilir.
     • Kod yazarken “bu bölüme sonra tekrar bakmalıyım” veya “bu özellik daha sonra geliştirilmeli” diye düşündüğünüzde, bu yöntem ilgili konuları kaydetmenizi ve takip etmenizi sağlar.
     • Kullanışlı bir extension: TODO Highlight
  3. Yorumlarla kodu mazur göstermeyin
     • Hatalı veya belirsiz kodu yorumlarla açıklayıp mazur göstermeye çalışmak yerine, kodu yeniden yazın.
     • Bazı kodların yorumla açıklanması gerekir; ancak bazı kodlar yoruma dayanmadan “kodun kendisiyle” konuşmalıdır.
  4. Yapay zekadan yararlanın
     • Yapay zeka yorum üreticileri kullanılırsa, belirli standartlara göre tutarlı biçimde yorumlar oluşturulabilir.
     • Tüm projede yorumların tutarlılığı korunabildiği için kodun okunabilirliği artar.
     • Kullanışlı bir yapay zeka yorum üreticisi: Readable

[penza1]

Yoruma ihtiyaç var gibi görünüyorsa
önce kodda bir sorun olup olmadığını düşünmek iyi olabilir.

Kodla birlikte yaşamayan, işleviyle birlikte güncellenmeyen yorumlar; gelecekte o yorumu görecek geliştiricilere ya da bana bile kafa karışıklığı yaratabilir.

Geçmişteki bağlam bugünle artık ilgili değilse ya da hata üretmeye başlamışsa bile,
o geçmiş bağlamı anlatan cümle yüzünden mevcut değişikliği yapmada tereddüt edebilir ya da başka bir yapıyla çözmek yerine dolanmak zorunda kalabiliriz.
Bu da daha fazla hataya yol açabilir..

Deneyimime göre, o zaman doğru olup bugün neden yanlış olduğunu gerçekten açıklayan yorumlar çok fazla olmuyor....

[ironlung]

Değerli görüşünüzü paylaştığınız için teşekkür ederim. Paylaştığınız görüş üzerine düşününce, kodun gelişimi için de yorumların gerekliliğini titizlikle yeniden sorgulama çabasının gerekli olduğunu düşünüyorum. :)

[aqqnucs]

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq

Bunu izlerken ben de yine yorumları gereğinden fazla yazmamaya çalışıyorum

[ironlung]

Bu güzel videoyu paylaştığınız için teşekkürler! :)

[iamchanii]

Yollar ne kadar iyi döşenmiş olursa olsun, yön tabelalarının mutlaka gerekli olduğunu düşünüyorum. Bu yüzden son zamanlarda yorum yazmayı bir alışkanlık haline getirmeye çalışıyorum.

[ironlung]

Yorumlarda görüşlerinizi paylaştığınız için teşekkür ederim. Söylediklerinizi düşününce, yorumların da önemli bir teknik yazım alanı olduğunu fark edip yazının temel ilkelerine yeniden dönüp bakmama vesile oluyor. :)

[balak]

Kodsuz açıklama gerektirmeyecek kadar anlaşılır kod yazmanın en iyisi olduğunu düşünüyorum.

[ironlung]

Evet, önce temellere sadık kalmanın öncelikli olduğunu düşünüyorum. Yorumunuz için teşekkürler. :)