Kural
Kodun ne yaptığını değil, amacını (nedenini) açıklayan yorumlar yazın (nasıl yapıldığını değil).
Yalnızca kodun ne yaptığını tekrar eden yorumlar
ekstra bir değer sunmaz ve zamanla güncelliğini yitirebilir.
Desteklenen diller: 45+Giriş
Kodun ne yaptığını tekrarlayan yorumlar ekstra bir netlik sağlamaz ve genellikle implementasyonla senkronizasyonunu yitirir. Yorumlar koddan farklılaşmaya başladığında kafa karışıklığı yaratır ve kod incelemelerini (review) yavaşlatır. Faydalı yorumlar; niyeti, varsayımları ve kararların arkasındaki gerekçeleri açıklar. Bu da karmaşık mantığın anlaşılmasını ve sürdürülmesini kolaylaştırır.
Neden önemli?
Güvenlik etkileri: Amaca yönelik yorumlar; validasyon, girdi güveni veya erişim kontrolü gibi implementasyonda hemen görünmeyebilecek varsayımları ortaya çıkarır.
Performans etkisi: Performansla ilgili kararları netleştiren yorumlar, kazara yapılan optimizasyonların veya beklenen performans özelliklerini bozan değişikliklerin önüne geçilmesine yardımcı olur.
Kodun sürdürülebilirliği: Amaca odaklanan yorumlar, geliştiricilerin bir kod parçasının neden var olduğunu anlamasına yardımcı olarak kodun değiştirilmesi veya denetlenmesi için gereken süreyi kısaltır.
Saldırı yüzeyi: Net yorumlar, güvensiz davranışlara yol açabilecek veya saldırı yüzeyini genişletebilecek şekilde dahili fonksiyonların yanlış kullanılma olasılığını azaltır.
Kod örnekleri
❌ Kural dışı:
// Loop through users
for (const user of users) {
// Convert email to lowercase
user.email = user.email.toLowerCase();
}Neden yanlış: Bu yorumlar kodun zaten gösterdiği şeyleri tekrarlamakta olup niyet veya kısıtlamalar hakkında hiçbir bağlam sunmamaktadır.
✅ Kurallara uygun:
/**
* Normalize user emails so downstream permission checks
* compare consistent lowercase values. Required because
* external systems may send mixed-case emails.
*/
for (const user of users) {
user.email = user.email.toLowerCase();
}Neden önemli: Yorum, normalizasyonun neden gerekli olduğunu açıklayarak niyeti netleştirir ve yanlış refaktör etme (refactoring) durumlarını önler.
Sonuç
Her satırın ne gösterdiğini değil, kodun neden gerekli olduğunu açıklayan yorumlar yazın. Implementasyondan açıkça anlaşılmayan durumlarda varsayımları, kısıtlamaları ve mantıksal gerekçeleri tanımlayın. Bu, kod geliştiğinde bile yararlılığını koruyan sürdürülebilir bir dokümantasyon oluşturur.
