Yorumlar ve Dokümantasyon
JavaScript’te yorumlar ve dokümantasyon, kodun anlaşılabilir, sürdürülebilir ve iş birliğine uygun olmasını sağlayan temel araçlardır. Kod yazarken, yorumlar adeta bir evin planları gibidir; duvarların nerede olacağını gösterir ve ileride yapılacak değişiklikler için yol gösterir. Dokümantasyon ise, bu evi nasıl döşeyeceğinizi açıklayan rehber gibidir.
Kişisel web sitenizde, yorumlar hangi fonksiyonun hangi sayfaya içerik yüklediğini açıklamak için kullanılabilir. Bir blog projesinde, yorumlar hangi bölümün yazıların listesini gösterdiğini ve hangi fonksiyonun yorumları yönettiğini belirtir. E-ticaret sitelerinde, sepet toplamını hesaplayan fonksiyonların amacı ve nasıl çalıştıkları yorumlarla açıklanabilir. Haber sitelerinde, içerik güncellemeleri ve kullanıcı etkileşimleri yorumlarla belgelenebilir.
Bu tutorial boyunca, yorum yazmanın ve dokümantasyon oluşturmanın temellerini öğrenecek, gerçek projelerde nasıl uygulanacağını göreceksiniz. Ayrıca, sık yapılan hataları ve en iyi uygulamaları öğrenecek, kodunuzu gelecekte başkalarının da kolayca anlayabileceği bir hale getireceksiniz. Yorumlar ve dokümantasyon, kodunuzu mektup gibi düzenlemek, karmaşık projelerde bile hızlı bir şekilde anlamayı mümkün kılar.
Temel Örnek
javascript// Function to calculate the square of a number
function square(num) {
return num * num; // Multiply number by itself
}
console.log(square(5)); // Expected output: 25Bu temel örnekte, yorumlar kodun amacını açıklamak için kullanılmıştır. İlk satırdaki // ile başlayan yorum, square fonksiyonunun ne yaptığını belirtir: bir sayının karesini hesaplamak. Bu basit bir fonksiyon olsa da, özellikle karmaşık fonksiyonlarda yorumlar kodu anlamayı kolaylaştırır.
Fonksiyon içinde, // Multiply number by itself yorumuyla işlem adım adım açıklanmıştır. Böylece başka bir geliştirici, num * num ifadesinin ne amaçla kullanıldığını hemen anlayabilir.
Son satırda console.log(square(5)); kodunun yanında yer alan yorum, beklenen çıktıyı belirtir. Bu, kodun doğruluğunu hızlıca kontrol etmeyi sağlar. Kişisel web sitesi veya blog projelerinde benzer şekilde, hangi fonksiyonun hangi veri ile çalıştığını açıklamak, kodun ileride bakımını kolaylaştırır. Başlangıç seviyesindeki bir geliştirici sıkça sorabilir: “Her satırı mı yorumlamalıyım?” Cevap hayırdır; yalnızca karmaşık veya önemli mantık adımlarını açıklamak yeterlidir.
Pratik Örnek
javascript// Function to calculate total price with discount in an e-commerce
function calculateTotal(items, discount) {
// Sum the prices of all items
let subtotal = items.reduce((acc, item) => acc + item.price, 0);
// Apply discount to subtotal
let total = subtotal - (subtotal * discount);
return total; // Final total after discount
}
// Example usage
let cart = \[{price: 30}, {price: 20}, {price: 50}];
console.log(calculateTotal(cart, 0.1)); // Expected output: 90Daha pratik bir örnekte, e-ticaret senaryosunu ele alıyoruz. calculateTotal fonksiyonu, ürün listesi ve indirim oranı alarak toplam fiyatı hesaplıyor.
İlk yorum, reduce metodu ile ürün fiyatlarının toplamını hesapladığımızı açıklıyor. Bu, özellikle reduce metoduna yeni başlayanlar için faydalıdır. İkinci yorum, indirimin toplam fiyata nasıl uygulandığını belirtir. Son yorum ise fonksiyonun döndürdüğü değeri açıklıyor: indirim sonrası toplam fiyat.
Örnek kullanım satırında, yorum beklenen çıktıyı gösteriyor. Bu tarz açıklamalar, haber siteleri veya bloglarda benzer hesaplamalar yapılırken kodun hızlı anlaşılmasını sağlar. Kodun karmaşıklığı arttıkça, yorumlar kodu mektup gibi düzenleyerek başkalarının veya sizin gelecekteki kendinizin anlamasını kolaylaştırır.
En iyi uygulamalar arasında şunlar vardır: modern sözdizimini kullanmak, yorumları güncel tutmak, fonksiyonları ve parametreleri açıklamak ve JSDoc gibi araçlarla yapılandırılmış dokümantasyon oluşturmak. Ayrıca performansı optimize etmek ve hata kontrolünü dokümante etmek önemlidir.
Yapılan yaygın hatalar arasında gereksiz yorum yazmak, eski yorumları bırakmak, belirsiz veya kafa karıştırıcı dil kullanmak ve isimlendirme yerine yorum kullanmak yer alır. Bellek sızıntıları veya yanlış olay yönetimi gibi hataları önlemek için, yorumlarla hangi bölümün ne yaptığı net şekilde belirtilmelidir.
Hata ayıklama ipuçları: test amaçlı geçici yorumlar ekleyerek kodun hangi bölümünü kontrol ettiğinizi belirtebilirsiniz. Bu yöntem, kodu birkaç saat sonra tekrar incelediğinizde anlaşılmasını kolaylaştırır.
📊 Hızlı Referans
| Property/Method | Description | Example |
|---|---|---|
| // | Tek satırlık yorum | // Display message |
| /* ... */ | Çok satırlı yorum | /* Explain multiple lines */ |
| / ... */ | JSDoc stili dokümantasyon | / Function to calculate total */ |
| JSDoc @param | Fonksiyon parametrelerini açıklama | @param {number} price - product price |
| JSDoc @return | Fonksiyon dönüş değerini açıklama | @return {number} total with discount |
Özetle, yorumlar ve dokümantasyon kodun anlaşılabilir ve sürdürülebilir olmasını sağlar. Kişisel web sitelerinden e-ticaret sitelerine kadar tüm projelerde, yorumlar kodun hangi bölümünün ne yaptığını netleştirir.
HTML DOM manipülasyonu veya backend ile veri alışverişi yaparken, yorumlar hangi elemanın değiştirildiğini veya hangi verinin gönderilip alındığını açıklamak için kullanılır.
Bir sonraki adım olarak, JSDoc kullanımını derinlemesine öğrenebilir, proje dokümantasyon standartlarını inceleyebilir ve Git ile entegre çalışmayı keşfedebilirsiniz. Pratik tavsiye: yorumları mektup gibi düşünün; her önemli bölümü etiketleyin ve kodunuzu gelecekte okunabilir kılın.
🧠 Bilginizi Test Edin
Bilginizi Test Edin
Bu konudaki anlayışınızı pratik sorularla test edin.
📝 Talimatlar
- Her soruyu dikkatle okuyun
- Her soru için en iyi cevabı seçin
- Quiz'i istediğiniz kadar tekrar alabilirsiniz
- İlerlemeniz üstte gösterilecek