JSDoc, TypeScript'tir

 (culi.bearblog.dev)
1 puan yazan GN⁺ 2025-12-16 | 1 yorum | WhatsApp'ta paylaş
  • 2023'te Svelte deposundaki refactoring PR, JSDoc tabanlı koda geçişle TypeScript şüphecilerinin dikkatini çekti
  • Svelte ekibi bunun TypeScript karşıtı bir duruş değil, TypeScript'e süregelen bağımlılığın bir parçası olduğunu açıkladı
  • Yazı, JSDoc ile TypeScript'i karşı karşıya koymak yerine, JSDoc'un bizzat TypeScript'in bir parçası olduğunu vurguluyor
  • TypeScript, bir IntelliSense motoru olarak hem JSDoc yorumlarını çözümleme hem de kod otomatik tamamlama işlevlerini üstleniyor
  • JSDoc, build aşaması olmadan aynı statik analiz yeteneğini sağlıyor ve modern JS projelerinde fiilen TypeScript ile aynı rolü oynuyor

Svelte PR'ı ve tartışmanın arka planı

  • Mayıs 2023'te, Svelte deposundaki dahili refactoring PR Hacker News ana sayfasına çıktı
    • Bu PR, .ts dosyalarındaki tip bildirimlerini .js dosyalarındaki JSDoc yorumlarına taşıyan bir değişiklikti
    • Bazıları bunu TypeScript'in avantajlarını reddeden bir hareket olarak yorumladı
  • Svelte'in yaratıcısı Rich Harris, HN'de doğrudan bunun “TypeScript karşıtlığı olmadığını” açıkladı
    • Svelte'in TypeScript'e bağlılığının hâlâ güçlü olduğunu belirtti
  • Bu olayın ardından, “TypeScript vs JSDoc” karşılaştırma yazıları çoğaldı ve JSDoc'u “build aşaması olmayan TypeScript” olarak değerlendiren yaklaşım yaygınlaştı

TypeScript'in kökeni ve özü

  • 2000'lerin sonu ile 2010'ların başında JavaScript, otomatik tamamlama ve tip güvenliği açısından yetersiz bir dil olarak görülüyordu
    • Microsoft geliştiricileri buna, C# kodunu JS'e dönüştürmek için ScriptSharp kullanarak karşılık veriyordu
  • Bu arka planda TypeScript doğdu; özünde, JS geliştirmeyi iyileştirmeye yönelik bir build aracı olarak yola çıktı

TypeScript, IntelliSense'tir

  • TypeScript yalnızca bir dil değil, bir IntelliSense motoru işlevi görüyor
    • .ts dosyaları kullanılmasa bile, kod otomatik tamamlama, parametre bilgisi ve sembol gezintisi gibi özellikler TypeScript dil servisi tarafından sağlanıyor
    • Çoğu editörde JS kodu yazarken bile arka planda TypeScript servisi çalışıyor

TypeScript, JSDoc'tur

  • TypeScript dil servisi, JSDoc yorumlarının çözümlemesinde de kullanılıyor
    • TypeScript'in CHANGELOG kayıtlarında JSDoc ile ilgili yeni özellikler sıkça yer alıyor
    • JSDoc tabanlı projeler de tsconfig.json ile yapılandırılabiliyor ve tsc komutuyla tip denetimi yapılabiliyor
  • Dolayısıyla JSDoc kullanan geliştiriciler de aslında zaten TypeScript kullanıyor

JSDoc tabanlı proje deneyimi

  • Yazar, mevcut bir projenin frontend'ini JSDoc tip açıklamaları tabanında yeniden yazma deneyimini paylaşıyor
    • Enum gibi çalışma zamanı özellikleri dışında, TypeScript'teki ifadelerin çoğu JSDoc ile mümkün
    • Generics sözdizimi biraz daha karmaşık olsa da, tip çıkarımını daha etkin kullanmayı teşvik ediyor
  • JSDoc projelerinde bir fonksiyona tıklandığında gerçek koda gidilebilmesi, geliştirme deneyimini iyileştiriyor
  • TypeScript araç ekosistemi, JSDoc projelerinde de yeniden kullanılabiliyor
    • Örneğin OpenAPI veya GraphQL şemalarından tip üreten kütüphaneler, tipleri JSDoc yorumları biçiminde de oluşturabiliyor

Sonuç ve ek örnekler

  • JSDoc, TypeScript'e bir alternatif değil; aynı statik analiz sistemini paylaşıyor
    • Build aşamasını atlayıp yine de eşdeğer tip güvenliği sunuyor
  • Ayrıca webpack projesinin de JSDoc'a taşındığı bir örnekten söz ediliyor
  • Bir TypeScript uzmanı olarak yazar, “JSDoc, TypeScript'tir” görüşünü açık biçimde ortaya koyuyor

İlgili okumalar

1 yorum

 
GN⁺ 2025-12-16
Hacker News görüşleri

  • Uzun yıllar boyunca Python/JavaScript ile web ve robotik yazılımları geliştirip bakımını yaparken öğrendiğim dersleri özetlemiş
    Tipler, açıkça belirtilmese de vardır; belirtilmezlerse sonunda yalnızca kafanızın içinde var olurlar
    Ama zihin çok uçucudur ve başkalarının erişmesi zordur
    Bu yüzden tipleme harika bir dokümantasyon aracıdır
    JSDoc ve TypeScript, tipleri ifade etmenin standart biçimleridir ve ikisinin de artıları ile eksileri vardır
    Önemli olan, tipleri tutarlı ve öngörülebilir şekilde tanımlamaktır
    Tip denetleyici, bilgisayarın “o zaman kanıtla” deme biçimidir
    Her program aynı düzeyde kanıt gerektirmez ve aşırı kanıt bir israf olabilir
    Bu yüzden ben, yalnızca gerektiği kadar “kanıtlanabilir” olan dilleri tercih ediyorum

    • “Yalnızca kafanın içindeki bilgi çok uçucudur” sözüne tamamen katılıyorum
      Özellikle ‘başkaları’na gelecekteki benliğimin de dahil olduğunu çalışırken acı şekilde öğrendim
    • Rust, “prove it” felsefesinin temsilcisi olarak bilinir ama gerçekte öyle olmadığını düşünüyorum
      Rust, unsafe, Arc, clone gibi yollarla kısıtları gevşetebilir; ama bunun karşılığında hangi kısıtların kanıtlanmadığını açıkça seçmenizi sağlar
      Buna karşılık, “kanıtlamak zorunda olmadığınız” dillerin içeride hangi yaklaşımı seçtiğini anlamak zordur
      Rust’ın yaklaşımı başta Python kadar gevşek hissettirebilir ama sonrasında okunabilirlik ve ölçeklenebilirlik açısından çok daha avantajlıdır
    • JSDoc ile TypeScript’in aynı amaca sahip olduğu görüşüne katılıyorum
      Belirli bir aracı savunma niyetim yoktu; sadece ikisinin de tip sistemini ifade etme biçimleri olduğunu vurgulamak istedim
    • Bu dersi 25 yıl önce üniversitedeyken öğrenmiştim
      Statik tiplemeli diller ekip projelerinde çok daha kolay yönetiliyordu ve bugün de mümkün olduğunda statik tipleri tercih ediyorum
    • “Tipler her zaman vardır” sözüne katılıyorum ama C# gibi tiplerin açıkça yazılması gereken diller, Ruby’ye kıyasla çok daha fazla iş gerektiriyor
      Mevcut JS kütüphanelerine sonradan eklenen TypeScript tip tanımlarına bakınca karmaşıklık muazzam boyutta
      Tek bir hatalı tip bile tüm derlemeyi bozabiliyor
      Sonuçta dinamik diller, ‘sorumluluğu kendin üstlenerek’ kullanılmalı

  • Ben build step olmadan JavaScript ile yapılabilen her şeyi seviyorum
    Modern HTML/CSS, Web Components ve JSDoc birleşimi yeterince değer görmüyor
    Herkese uygun olmayabilir ama yeterince modern bir frontend stack adayı olduğunu düşünüyorum

    • Artık Node 24 ile birlikte TypeScript de build step olmadan çalıştırılabiliyor
    • Build step’siz yaklaşımın cazibesini anlıyorum ama pratikte bağımlılık yönetimi daha karmaşık hale geliyor
      HMR gibi özellikler sayesinde build step’in maliyeti de oldukça azaldı
    • Son 10 yılda gerçekten dağıtılmış JS kodunu doğrudan yazdığım olmadı
      Her zaman Vite veya Webpack üzerinden geçtiği için build’siz JS’nin avantajını pek hissetmiyorum
    • Web Components oluşturmak epey sancılı
      Keşke karmaşık bileşenleri daha kolay üretmenin bir yolu olsa
    • HTML+CSS+JSDoc birleşiminin avantajı, tarayıcı geliştirici araçlarıyla doğal entegrasyon sağlaması
      Ağ isteklerini izleme, doğrudan kaynak koda gitme, breakpoint koyma gibi şeylerde hata ayıklama çok daha sezgisel oluyor
      Ölçek büyüdükçe böyle bir ortam büyük fayda sağlıyor

  • SPA’lerin popüler olduğu dönemde JSDoc, tip yönetiminin kurtarıcısıydı
    Sonrasında Google Closure Compiler çıktı ve JSDoc tabanlı tip güvenliği sundu; TypeScript ise kendi sözdizimiyle birlikte (TS)JSDoc desteği verdi
    Topluluk sonunda TypeScript’i seçti ve Closure Compiler ortadan kayboldu
    Bu yüzden (TS)JSDoc, MS’in Google ile rekabet ettiği dönemin bir kalıntısı olarak kaldı
    Bugün TS; generics, Enum, utility type’lar, Vitest tip testleri, type guard’lar gibi çok daha fazla özellik sunuyor
    Ben TS ile JSDoc’u birlikte kullanıyorum — TS kod için, JSDoc ise dokümantasyon için (@link, @see, @deprecated, @example vb.)

    • Aslında modern JSDoc, TypeScript language service kullanıyor
      Generics, utility type’lar, type guard’lar, regex parsing gibi TS’nin çoğu özelliği JSDoc içinde de kullanılabiliyor
      Kişisel projelerimde generics dahil her şeyi tamamen JSDoc ile kurmayı denedim
    • Yukarıdaki iddia doğru değil
      (TS)JSDoc’un geçmişten kalma bir kalıntı olduğu söylemi yanlış bilgi; doğrulamadan yayılmamalı
    • Bu yazının kendisi zaten o iddiaya karşı doğrudan bir çürütme niteliğinde

  • JSDoc ile ifade edilemeyen çok sayıda tip olduğu söyleniyor ama Flow gibi tüm dili kapsayan bir yaklaşım mümkün olsaydı güzel olurdu
    TypeScript de bunu yapabilirdi, neden yapmadı bilmiyorum

    • Somut bir örnek varsa duymak isterim
      Ben de eskiden böyle düşünüyordum ama projeyi JSDoc’a refactor ederken fikrim değişti
      JSDoc’ta da @template ile generic slot’lar tanımlanabiliyor
      Örnek: 
      /** @type {ReturnType<typeof useState<Book[]>>} */
const [books, setBooks] = useState();
    • Artık neredeyse tüm tip sistemi özellikleri JSDoc sözdizimine de eklendi
    • TypeScript’in tip sistemi Turing complete olduğu için fiilen sınırsız ifade gücüne sahip
      İlgili bağlantı

  • JSDoc ile yazılmış paketlerde CMD/CTRL+tık ile doğrudan gerçek koda gidilebilmesi geliştirici deneyimi açısından güzel

    • Bu, editör ayarlarıyla da özelleştirilebilir
    • Aslında TypeScript’te de aynı şekilde çalışıyor

  • 5 yıl önce bir meetup’ta bir konuşmacı “TypeScript’i sevmiyorsanız JSDoc bir alternatiftir” demişti
    Ben bunun aslında ikisinin de TypeScript olduğunu açıklamıştım ama yöneticim bana inanmamıştı

    • Aradaki farkın sözdiziminin sıkıştırma derecesi (syntax compression) olduğunu düşünüyorum
    • “JSDoc da sonuçta TypeScript’tir” sözü yarı yarıya doğru
      JSDoc ile TS, tipleri açıkça ifade etme bakımından ortaktır ama TS sözdizimi çok daha güçlüdür
      Yine de JS ortamını korurken tip araçlarının faydasını almak isteyenler için JSDoc iyi bir seçimdir

  • Karşı argüman olarak, JSDoc TypeScript değildir
    @typedef ile tanımlanan tipler otomatik olarak export edilir ve bunu kontrol etmenin bir yolu yoktur
    İlgili issue
    Bu yüzden kütüphane geliştirirken IntelliSense dağınık şekilde görünerek rahatsız edici olmuştu

    • Web Components için JSDoc epey iyi uyuyor
      “my-component.js” dosyasını olduğu gibi kopyalasanız bile build olmadan çalışıyor
      Ama büyük projelerde TS sözdizimini tercih ediyorum
    • Teknik olarak doğru bir nokta ama @import’u ayarlayarak çoğu durumda çözülebilir

  • “JSDoc, TypeScript’in alternatifi değildir” iddiasına katılıyorum
    JSDoc da statik analiz sağlar ama build step gerektirmez
    Node resmi dokümantasyonu bkz.

    • İçeride hâlâ bir build step var
      Ama JSDoc tabanlı TS tarayıcıda da çalışıyor
      Ben kişisel olarak TS sözdiziminin okunabilirliğini tercih ediyorum ve swc gibi araçlarla tiplerin kaldırılma hızı da fazlasıyla yeterli
    • Ancak bu özellik Node ortamıyla sınırlı ve tarayıcıda çalışmıyor

  • TypeScript’in diğer alternatifleri geride bırakıp kazanmasının nedeni, yeni bir dil değil bir tip denetleyici olarak kalmasıydı
    Başlarda yönü biraz sallantılıydı ama zamanında düzeltildi; bugün çoğu kodda enum’lar bile pek kullanılmıyor

  • VSCode’da “TypeScript: Prefer Go To Source Definition” ayarını açarsanız gerçek kaynağa gidebilirsiniz
    Ayrıca tsconfig içine declarationMap: true eklenirse daha doğru çalışır
    Ben neredeyse her zaman cmd+click ile kaynağı görmeyi tercih ediyorum