JS界隈にIDLもしくはd.tsを併記・同梱する文化が根付いてほしい

前置き

最近、ウェッブフロントエンドエンジニアらしく各種JavaScriptのライブラリを眺めて、調査・選定しているのだけれども、その過程を通じたこととして、多くのライブラリが、ドキュメントのAPIの説明が貧弱すぎる。

jQueryのドキュメントが腐っているというのは既に広く知られた事実であると思うし、そうでないならば積極的に既知の事実として腐っている事を広めて行くべきであると強く思うが、jQueryに限らずとも、ドキュメントが満足な形で整理されていないのをひしひしと感じる。

この手のものでよくドキュメント化されている部類だと感じるBackbone.jsですら、仮引数の名称と定義のみしか書かれておらず、肝心の引数が備えるべきメンバや、引数の型情報が明示的に記述されていない。そのため、APIを俯瞰し、自分の欲しい情報がどこに詰まっているのか・どのように取得できるのか・DOM標準もしくはECMA262標準との対応がどのようになっているのかを眺めて確認するのが困難だと痛感している。

MarionetteやChaplinなども割とマシな部類ではあるし、プリミティブな値についてはbooleanなどのように表記がなされているが、eventなどのような引数に成ると、DOM Eventなのか、Backbone.Eventsが飛んでくるのかを、文書のコンテクストを咀嚼した上で解釈しなければならなかったり、使い方・思想と混在してAPIが語られているので本当に読みにくい。

この点、Vue.jsなどは、APIのドキュメントが引数の型を明示している、かつドキュメント事態の記述が明瞭簡潔なので、かなりマシな方。個人的には、Objectなどのようにざっくりと書くよりは「最低限このメンバを持って居てほしい」ということでinterfaceを定義するなりしてほしいのだけれども、他が酷すぎるのと、JavaScriptの動的な性質を鑑みると、この水準があれば足る、一種の均衡点だと思う。

主張

私が主張したいのは、ライブラリを公開するにあたっては、APIのシグニチャだけでいいので公開しておいてほしいということ。大層なHow to UseやBoilerplateなどは無くてもいい。ただ、ライブラリの設計哲学とAPIの一式をIDLまたはTypeScriptのd.ts、最悪はコード中のJSDocの形式で表現しておくようにしておいて欲しいということ。どうせGithubもしくはBitbucketにホスティングするのだからmarkdownで簡単に書けるはず。

それを言い出すとECMA262仕様はどうなんだというツッコミが入りそうだけれども、あれに動的型付け言語でFunction.prototype.callで任意のコンテクストを伴って呼ばれうる関数が大量にあることを考えると仕方ないのではないか。むしろ、Function.prototype.callで任意に呼びされる可能性も無く、そんなことをすると確実に挙動が壊れるAPI設計をしていて、おまけにJavaっぽくクラスだのなんだのと名乗るお前のライブラリにIDLが無い事の方が問題。

JavaScriptで記述されるアプリケーションが複雑化するに伴って、単にJITコンパイラに対して情報を提供するという以上に、静的検査などを用いて複雑性の軽減を図るために、JSの世界でも「型」という情報は重視・一般化されつつあるのが現状である。Closure Compiler, TypeScriptなどはその急先鋒であるわけで、ES7には、ES6からpostponeされたTypedObject（構造体定義の導入）がproposalとして上がっていることを考えると、JSにおける型情報の提供というのは希求されているものであることが伺える。

こうした現状を踏まえた上で、理想であれば(Web)IDL, せめてTypeScriptのd.tsによるインターフェースの情報を提供するのが一般化してほしいと強く願う。

結論

とどのつまり、オサレな配布ページをgithub pageで作成するような暇があるのならば、README.mdの一部にAPIってセクションを貼って、IDLを書いて載せろということです。