Kural
İşlevler açıklama açıklayıcı açıklamalar.
İşlevler açıklayıcı açıklama işlevler zor anlaşılması
anlaşması diğerleri diğer geliştiriciler.
Desteklenen diller: 45+Giriş
Yorum içermeyen işlevler, geliştiricileri niyeti yalnızca uygulama ayrıntılarından çıkarmaya zorlar. Bu durum kod incelemelerini yavaşlatır ve bakım sürecini hatalara daha açık hale getirir. Açıklamaların eksikliği, doğrulama, girdi beklentileri veya güvenlik kısıtlamalarıyla ilgili varsayımları da gizler. Net bir dokümantasyon, yanlış kullanımı azaltır ve ekiplerin kodun davranışını daha hızlı anlamasına yardımcı olur.
Neden önemli?
Güvenlik açısından etkileri: Eksik yorumlar, doğrulama, yetkilendirme kontrolleri ve güvenilir girdilerle ilgili varsayımları gizler; bu da kötüye kullanımı kolaylaştırır ve güvenlik risklerini artırır.
Performans üzerindeki etkisi: Belgelenmemiş işlevler yanlış kullanılabilir; bu da tekrarlanan ve kaynak tüketen işlemlerin, gereksiz ayrıştırma işlemlerinin veya verimsiz veri işleme süreçlerinin ortaya çıkmasına neden olabilir.
Bakım Kolaylığı: Amaç belgelenmediğinde, geliştiriciler mantığı okumak ve tersine mühendislik yapmak için daha fazla zaman harcarlar; bu da yeniden yapılandırma ve yeni çalışanların işe alıştırma süreçlerini yavaşlatır.
Kod örnekleri
❌ Uygun değil:
// 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ış: Bu işlev, güvenlikle ilgili alanları işliyor ancak güvenilir kaynaklar, beklenen yapı veya girdi kısıtlamaları hakkındaki varsayımları belgelemiyor.
✅ Uygunluk:
/**
* 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')
};
}Bunun önemi: Bu açıklama, amaçları, beklenen girdileri ve güvenlik kısıtlamalarını ortaya koyarak, kullanımın öngörülebilir olmasını sağlar ve güvenli olmayan entegrasyonu önler.
Sonuç
İmzadan amaç, varsayımlar veya kısıtlamalar açıkça anlaşılmayan herhangi bir fonksiyona net açıklamalar ekleyin. Fonksiyonun ne beklediğini, ne döndürdüğünü ve güvenlikle ilgili tüm davranışları belgelendirin. Bu, inceleme kalitesini artırır, yanlış kullanımı azaltır ve kod tabanı genelinde öngörülebilir davranış sağlar.
