Kural
Yorum hakkında hedef hedef (neden), golle mekanik işleyiş (ne).
Yorumlar ki sadece yeniden ifade eden ne kod kod yaptığını
sağlamıyor hiçbir ek değer ve olabilir modası geçmiş eski hale gelebilir.
Desteklenen diller: 45+Giriş
Kodun ne yaptığını tekrarlayan yorumlar, ek bir açıklık sağlamaz ve genellikle uygulama ile uyumsuz hale gelir. Yorumlar koddan saptığında, kafa karışıklığına yol açar ve inceleme sürecini yavaşlatır. Yararlı yorumlar, kararların ardındaki niyeti, varsayımları ve mantığı açıklar. Bu da karmaşık mantığın anlaşılmasını ve bakımını kolaylaştırır.
Neden önemli?
Güvenlik açısından etkileri: Niyet temelli yorumlar, uygulamada görünmeyebilecek olan doğrulama, girdi güvenilirliği veya erişim kontrolü ile ilgili varsayımları ortaya çıkarır.
Performans üzerindeki etkisi: Performansla ilgili kararları açıklayan yorumlar, beklenmedik optimizasyonların veya beklenen performans özelliklerini bozan değişikliklerin önlenmesine yardımcı olur.
Kodun bakım kolaylığı: Amaç odaklı açıklamalar, geliştiricilerin bir kod parçasının neden var olduğunu anlamalarına yardımcı olur ve bu sayede kodu değiştirmek veya denetlemek için gereken süreyi azaltır.
Saldırı yüzeyi: Açık ve net açıklamalar, güvenli olmayan davranışlara yol açacak veya saldırı yüzeyini genişletecek şekilde dahili işlevlerin kötüye kullanılma olasılığını azaltır.
Kod örnekleri
❌ Uygun değil:
// 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 bilgileri tekrarlıyor ve amaç ya da kısıtlamalar hakkında hiçbir bağlam sağlamıyor.
✅ Uygunluk:
/**
* 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();
}Bunun önemi: Bu açıklama, normalleştirmenin neden gerekli olduğunu ortaya koyarak amacını netleştirir ve hatalı yeniden yapılandırmayı önler.
Sonuç
Yorumlarınızı, her satırın halihazırda neyi gösterdiğini değil, kodun neden gerekli olduğunu açıklayacak şekilde yazın. Uygulamadan açıkça anlaşılmayan varsayımları, kısıtlamaları ve mantığı açıklayın. Bu, kod geliştikçe bile yararlı kalacak, bakımı kolay bir dokümantasyon oluşturur.
