**Soru:** Her fonksiyonun üstüne yorum yazmam gerekiyor mu? Takım liderim "iyi kod yorum gerektirmez" diyor ama başka kaynaklar "yorum yaz" diyor. Kim haklı? **Kısa Cevap:** Her ikisi de kısmen haklı. Yorum, kodun "ne" yaptığını değil "neden" yaptığını açıklamalıdır. "Ne" açık koddan okunur; "neden" çoğu zaman okunamaz. --- Kod yorumu ne zaman yazılmalı sorusu programlamada en çok tartışılan konulardan biridir. İki kutup da vardır: her satırı açıklayan aşırı yorumcu ve hiç yorum yazmayan minimalist. Gerçek ikisinin ortasında. **"İyi kod yorum gerektirmez", Ne zaman doğru?** Değişken ve fonksiyon isimleri anlamlıysa, kod sade akışla yazılmışsa yorum gerçekten gereksizdir. ```python # Kötü: x = a * 0.18 # KDV hesapla # İyi: tax_amount = price * VAT_RATE ``` İkinci versiyonda "KDV hesapla" yorumuna ihtiyaç yoktur. Kod kendini anlatır. Kod yorumu ne zaman yazılmalı sorusunun cevabı burada: bu tür durumlarda yazılmaz. **Yorum kesinlikle yazılmalı: "Neden" sorusu** Aşağıdaki durumda yorum zorunludur: ```python # Tarayıcı X'in 2021'deki Y bug'ı nedeniyle 1 saniye gecikme eklendi. # Bug raporu: JIRA-4521 time.sleep(1) ``` Bu satırı gören biri "neden sleep var?" diye sorar. Yorum olmasaydı ileride temizlik yaparken bu satırı siler ve bug yeniden çıkar. **Yorum yazılması gereken durumlar:** - Sezgisel görünmeyen kararlar (neden bu algoritma seçildi?) - Geçici çözümler (TODO veya FIXME ile birlikte) - Regex veya karmaşık matematiksel formüller - Public API belgeleme (docstring formatında) - Güvenlik veya iş kuralı nüansları **Yorumdan kaçınılması gereken durumlar:** - Kodun aynen tekrarlanması: `i = i + 1 # i'yi bir artır` - Güncel olmayan yorumlar (koddan daha tehlikeli) - Her satıra yorum (okunabilirliği düşürür) **Pratikte bir kural** Kod incelemesinde bir iş arkadaşın "Bu neden böyle?" diye soracağını hissediyorsan yorum yaz. Cevabı zaten koddan görebiliyorsa yazma. Kod yorumu ne zaman yazılmalı sorusunun en kısa yanıtı şu: kodun neden bu kararı aldığını gelecekteki okuyucuya aktarmak istediğinde yaz; sadece ne yaptığını tekrar etmek istediğinde yazma.