(Kod Konuşur… Ama İnsanlar İçin Altyazı Gerekir)

Bir gün eski bir projeni açarsın.
Ekrana bakarsın.
Kod sana bakar.

Aranızda sessiz bir gerilim oluşur.

“Bunu gerçekten ben mi yazdım?”

İşte o an yorum yazmanın değerini anlarsın.

JavaScript yorumları küçük görünür ama büyük krizleri önler.
Doğru kullanıldığında ekip içi iletişimi güçlendirir.
Yanlış kullanıldığında kod mezarlığına dönüşür.

Bugün yorumları sadece “// açıklama yazmak” olarak değil,
temiz kodun stratejik silahı olarak ele alıyoruz.

Hazırsan başlıyoruz.

1️⃣ Tek Satırlık Yorumlar (//)

(Kodun Kenarına Fısıldanan Notlar)

Tek satırlık yorumlar hızlıdır, pratiktir ve anlık düşünceler için idealdir.

// Kullanıcının doğum yılı
const birthYear = 1998;

Bu basit. Ama asıl olay şu:

Tek satırlık yorumlar genellikle bağlam verir.

🎯 Ne Zaman Kullanılır?

Bir satırın arkasındaki iş mantığını açıklamak için
Küçük uyarılar için
Debug sırasında geçici devre dışı bırakma için

⚠️ Debug İçin Kullanımı

const price = 100;
const discount = 20;

// const total = price - discount;
const total = price;

console.log(total);

Burada indirim geçici olarak devre dışı bırakıldı.

Ama dikkat:
Bu geçici durum kalıcı hale gelirse proje çöplüğe döner.

👉 Profesyonel ipucu:
Geçici yorum satırlarını iş bittikten sonra sil.

2️⃣ Çok Satırlı Yorumlar (/* */)

(Kodun İçindeki Mini Belgesel)

Çok satırlı yorumlar daha kapsamlı açıklamalar içindir.

/*
  Bu fonksiyon:
  - Kullanıcıdan gelen ham veriyi temizler
  - Gereksiz boşlukları kaldırır
  - Büyük harfe çevirir
*/
function normalizeInput(input) {
  return input.trim().toUpperCase();
}

Burada kod zaten kısa.
Ama gerçek projelerde işler karmaşık olur.

🎯 Gerçek Hayat Örneği

/*
  API'den gelen tarih formatı:
  "2026-02-13T08:15:30Z"

  Bu fonksiyon:
  1. Tarihi Date objesine çevirir
  2. Lokal saat dilimine göre formatlar
  3. UI için okunabilir string üretir
*/
function formatDate(apiDate) {
  const date = new Date(apiDate);
  return date.toLocaleString();
}

Bu yorum gelecekteki geliştiriciye şunu der:

“Burada bir iş var. Rastgele yazılmadı.”

3️⃣ Yorum Neden Yazılır? (Asıl Felsefe)

Kod ne yaptığını gösterir.
Yorum neden yaptığını açıklar.

❌ Kötü Örnek

// Sayıyı 2 ile çarpıyoruz
const result = number * 2;

Gereksiz.

✅ İyi Örnek

// API yüzde değeri yerine ondalık verdiği için 100 ile çarpıyoruz
const percentage = apiValue * 100;

Burada mantık var.
Bağlam var.
“Niye böyle saçma bir şey yaptık?” sorusunun cevabı var.

4️⃣ Karmaşık Mantıkta Yorum Hayat Kurtarır

Gerçek projelerde bazı kodlar…
“akıl sağlığını test eder.”

const finalPrice =
  user.isPremium &amp;&amp; cart.total > 500
    ? cart.total * 0.8
    : cart.total;

Bu tek satırda drama var.

Yorumla netleştirelim:

// Eğer kullanıcı premium ise ve sepet 500 TL üzerindeyse %20 indirim uygula
const finalPrice =
  user.isPremium &amp;&amp; cart.total > 500
    ? cart.total * 0.8
    : cart.total;

Şimdi daha insani.

5️⃣ JSDoc: Profesyonel Seviye Yorum

Büyük projelerde yorum sadece açıklama değil,
dokümantasyon aracıdır.

/**
 * İki sayıyı toplar
 * @param {number} a - Birinci sayı
 * @param {number} b - İkinci sayı
 * @returns {number} Toplam sonucu
 */
function sum(a, b) {
  return a + b;
}

Neden Önemli?

IDE otomatik öneri verir
Tip kontrolü kolaylaşır
Takım projelerinde büyük avantaj sağlar

Özellikle TypeScript kullanmıyorsan JSDoc altın değerindedir.

6️⃣ TODO, FIXME ve Teknik Borç

Gerçek hayatta hiçbir proje “tam mükemmel” değildir.

// TODO: Bu fonksiyon async yapılacak
// FIXME: API null döndüğünde hata fırlatıyor
// HACK: Bu çözüm geçici olarak yazıldı

Bu etiketler:

Ekip iletişimini güçlendirir
Teknik borcu görünür kılar
Kaosu düzenler

Ama dikkat:
TODO’lar sonsuza kadar kalmamalı.

7️⃣ Fazla Yorum Zararlıdır

Şimdi en kritik konu.

// Değişken tanımlıyoruz
let count = 0;

// 1 artırıyoruz
count++;

// Konsola yazdırıyoruz
console.log(count);

Bu eğitim videosu gibi.
Gerçek projede gereksiz.

Kod zaten okunabilir yazılmalı:

let loginAttemptCount = 0;
loginAttemptCount++;
console.log(loginAttemptCount);

İsimlendirme iyiyse yoruma gerek azalır.

8️⃣ Yorum mu Yazmalıyım, Kodu mu Basitleştirmeliyim?

Kendine şunu sor:

“Bu kodu anlamak için yorum gerekiyor mu?”

Eğer evet ise…

Belki kodu sadeleştirmek daha doğru.

Örneğin:

// Kullanıcı aktif ve admin değilse erişimi engelle
if (user.isActive === true &amp;&amp; user.role !== "admin") {

Daha okunabilir yaz:

const isRestrictedUser =
  user.isActive &amp;&amp; user.role !== "admin";

if (isRestrictedUser) {

Şimdi yoruma ihtiyaç azaldı.

9️⃣ En Büyük Gerçek

Yorumlar:

Gelecekteki sana mektuptur.
Takım arkadaşına rehberdir.
Karmaşık iş mantığının haritasıdır.

Ama:

Kod kötü ise yorum kurtaramaz.
Yorum kodun yerine geçemez.
Gereksiz yorum kodu kirletir.

🎬 Sonuç

Kod bilgisayar içindir.
Yorum insan içindir.

Ve yazılım dünyasında en tehlikeli cümle şudur:

“Ben bunu hatırlarım.”

Hayır.
Hatırlamazsın.

Yorum yaz.
Ama bilinçli yaz.
Az ama öz yaz.
Nedeni açıkla.
Bağlam ver.

Çünkü 6 ay sonra o projeye geri döndüğünde…

En iyi arkadaşın
yazdığın yorum olacak.

“JavaScript Yorumları: Kodunuzu Açıklamak ve Düzenlemek”