東京Node学園祭2015でESDocについて発表してきました

こんにちは丸山@です。

昨日、東京Node学園祭2015というNode.jsについての国内最大のイベントがありました。参加人数は400人くらいで、海外からも有名なゲスト招いており、2トラック同時並行で行われるというイベントでした。運営のみなさん本当にお疲れ様でした。非常に楽しかったです。イベントの内容全般については以下のリンクを見ると良いかと思います。

そこで僕も「ESDoc - ES6時代のドキュメンテーションツール -」というタイトルでESDocというES6(ECMAScript2015)向けのドキュメンテーションツールについて発表してきました。

ES6時代のAPIドキュメンテーションツール ESDocの大いなる野望 - Togetterまとめ

f:id:h13i32maru:20151108134700j:plain

こんな大規模なイベントで話しをするのは初めて出し、そもそも外で話をするのも3回目？くらいなので、めちゃくちゃ緊張しました。しかも緊張していたのはそれだけじゃなくて、「3セッション前に@さんが技術文書というドキュメント系の話をしていて、それがすごく良かった(僕もドキュメント系の話だった)」というのと「基調講演で@さんがこれからのECMAScriptはLiving Standardだからバージョン番号は気にしないよ(僕の発表タイトル参照)」っていう話をしていて、ヒヤヒヤしていたというのもあります。

でもなんとか無事に発表を終えることができて良かったです。発表したあとにtwitterを見てみると「良さそう」「使ってみよう」という声をちらほら見かけてありがたかったです。それとesdoc/esdocにスターくださいというのも話したらつけてくださる方も居て嬉しかったです。

こういう嬉しいツイートも。

型をドキュメントに書くことについての捕捉

質問やtwitterを見ているとTypeScriptやFacebook Flowなどの型ありの言語を使う場合についてのドキュメントをどうするか？みたいなのをちらほらみかけました。

発表中では型をエンドユーザ向けのマニュアル(以降はドキュメントと記載)に書くことは触れなかったのですが、やはり関心が向くところなのだと思います。静的型付け言語の場合は@paramや@return(以降はドキュメントコメントと記載)には当然書かなくて良いと思います。ただし、ドキュメンテーションツールはコード中の型情報を抜き出して、ドキュメントには記載しなければならないと思います。

では動的型付け言語の場合はというと、個人的にはドキュメントコメントに書くべきだと思っています。それならはじめから静的型付け言語を使えばいいじゃないかという話にもあるのですが、そういう考えもありだと思います。でも動的型付け言語の場合、プロトタイプやUI層の実装に向いていたり、ダックタイピングがしやすかったりというメリットがあると思っています。

しかし動的型付け言語のドキュメントコメントに型を書いていくと、どうしても実際とは違う間違った型を書いてしまったり、抜け漏れが出てきてしまいます。100歩譲って抜け漏れは仕方ないにしても、間違った型情報は害悪です。静的型付け言語の場合、コンパイラが型情報をチェックしてくれるので100%正確な型情報がつくことになります。この型情報をチェックする仕組みが動的型付け言語のドキュメンテーションツールもしくは型情報だけをチェックするツールがあれば間違った型情報や抜け漏れをかなり防げるのではないかと思います。実際そういうツールとして@さんが推しているColsure Compiler(Google製)というツールがあります。他にもJSDocedというドキュメントコメントから得た型情報をコード中に埋め込んでチェックするというアプローチをとっているものもあります。なので、「動的型付け言語に型情報を書くと間違いや抜け漏れが出るから、書かない」という方向に行くのではなく、その問題をツールで解決して、動的型付け言語のメリットを活かしつつ、良いドキュメントを作るために型情報を活用するという方向に行くべきだと思っています。もちろん言語自体に静的型付けと動的型付けの中間？のようにあとから型情報をヒントとして与えられるという方法もあるのだと思います（が僕はそこらへんの言語の話は詳しくないので雰囲気で書いてます）。

ちなみにドキュメントとしてこの型情報だけ書けば良いといわけでも無く、他にもいろいろ書くべきことがあるうちの一つだという認識を忘れずにいたいと思います。

ESDocについてのアイデアをもらえた

発表し終わったあとにESDocについてのアイデアをいくつか頂きました。@さんからは@testをもっと賢くするというようなアイデアを、@さんからはassertを自動的に抜き出してドキュメント化できないかというアイデアを頂きました。

こういうアイデアは自分一人でやっていてもなかなか得られないですし、何より自分一人で思いついたアイデアはそれに固執してしまいがちというのもあります。実際ESDocのテストコード統合機能は開発当時にhokacchaさんに相談しにいったらよいよいアイデアをもらえたというのがあります。他にもMarkdownを出力できるといいのでは？という話をしてくださった方も居ます。

こういうアイデアをもらえるのは非常に嬉しくてありがたい限りです。なのでできれば実装してみたいと思うのですが、なかなかにレベルの高いアイデアなのですぐには難しそうだなぁという感触です。その前にESDocの内部を整理しないといけなさそうです😇

冬コミの宣伝

@さんに誘われて冬コミにてTech Boosterさんのサークルから出版される本に少し書かせていただくことになりました。内容は今回発表したようなESDocについての話にする予定です。興味のある方はぜひお買い求めください。

CodeLunch.fm

だんだんとNode学園祭とは関係ない話になってきたんですが、今回のイベントにはCodeLunch.fmの自作パーカーを着て行きました。これまでCodeLunch.fmに出演された方で、このパーカーが欲しい方がいらっしゃれば僕まで連絡ください。無料でプレゼントいたします。

f:id:h13i32maru:20151024114846j:plain:w300

f:id:h13i32maru:20151024114942j:plain:w300

Node学園祭、非常に楽しいイベントでした。来年も楽しみにしています。

(ブログを書くまでがイベントの醍醐味ですよ、みなさん！）