Kural
Açıklayıcı yorumları olmayan fonksiyonlar.
Yorumsuz fonksiyonları diğer geliştiricilerin anlaması
zordur.
Desteklenen diller: 45+Giriş
Yorum içermeyen fonksiyonlar, geliştiricilerin niyeti yalnızca uygulama detaylarından yola çıkarak çıkarmak zorunda kalmasına neden olur. Bu durum kod incelemelerini yavaşlatır ve bakımı daha hataya açık hale getirir. Eksik açıklamalar ayrıca doğrulama, girdi beklentileri veya güvenlik kısıtlamaları etrafındaki varsayımları gizler. Net dokümantasyon yanlış kullanımı azaltır ve ekiplerin kod davranışını daha hızlı anlamasına yardımcı olur.
Neden önemli?
Güvenlik etkileri: Eksik yorumlar; doğrulama, yetkilendirme kontrolleri ve güvenilir girdiler etrafındaki varsayımları gizleyerek kötüye kullanımı kolaylaştırır ve güvenlik risklerini artırır.
Performans etkisi: Dokümante edilmeyen fonksiyonlar yanlış kullanılabilir; bu da tekrarlanan maliyetli işlemlere, gereksiz ayrıştırmaya (parsing) veya verimsiz veri işlemeye neden olur.
Sürdürülebilirlik: Niyet belgelenmediğinde geliştiriciler mantığı okumaya ve tersine mühendislik yapmaya daha fazla zaman harcar, bu da yeniden düzenlemeyi ve ekibe uyum sürecini yavaşlatır.
Kod örnekleri
❌ Kural dışı:
// No explanation of expected input or security assumptions
function normalizeUser(user) {
if (!user || typeof user !== 'object') return null;
return {
id: String(user.id).trim(),
email: user.email.toLowerCase(),
roles: user.roles.filter(r => r !== 'guest')
};
}Neden yanlış: Fonksiyon güvenlikle ilgili alanları işliyor ancak güvenilir kaynaklar, beklenen yapı veya girdi kısıtlamaları hakkındaki varsayımları belgelemiyor.
✅ Kurallara uygun:
/**
* Normalize user data from external input.
* Expects: `user` contains `id`, `email`, and `roles`.
* Rejects invalid structures and filters unsafe role values.
* Ensures normalized identifiers and lowercased email for consistency.
*/
function normalizeUser(user) {
if (!user || typeof user !== 'object') return null;
return {
id: String(user.id).trim(),
email: user.email.toLowerCase(),
roles: user.roles.filter(r => r !== 'guest')
};
}Neden önemli: Yorum; niyeti, beklenen girdileri ve güvenlik kısıtlamalarını belgelendirerek kullanımı öngörülebilir kılar ve güvenli olmayan entegrasyonları önler.
Sonuç
Niyetin, varsayımların veya kısıtlamaların imzadan açıkça anlaşılmadığı tüm fonksiyonlara net yorumlar ekleyin. Fonksiyonun ne beklediğini, ne döndürdüğünü ve güvenlikle ilgili olası davranışları belgelendirin. Bu, inceleme kalitesini artırır, yanlış kullanımı azaltır ve kod tabanı genelinde öngörülebilir bir davranış sağlar.
