最初にドキュメントから書く話。（JavaScriptおれおれAdvent Calendar 2014 – 17日目）

特にライブラリー的なものを作るとき、最初にドキュメントを書くようにしてます。

例えばこれ、まだドキュメントしかないです。

最初にドキュメントを書く効能

もちろん後で書く手間が省けるってのもあるけど、それより、最初にAPIのリファレンスを作る事で、成果物の最終形が明確になります。最終形が分かっていれば、ごりごり書いてそれに近づけるだけっすね。

APIが決まっていれば試験を書ける、試験が書ければリファクターができる、リファクターができれば雑なコードでも実装を進められる。とまあそんな感じ。

もしここで明確な最終形を記述できなかったとしたら、それは現時点ではまだ何を作れば良いかわかっていないという事になるでしょう。それだとコードも書けない。

製品内の部品を作る場合も、同じように最終形を最初に考えます。これはいちいちドキュメント作成したりはしない場面が多いけど、脳内には用意しておく。必要ならメモ書きくらいは作っても良い。

理由は前述のものと同じで、これから何を作るのかを確認するため。

短い紹介文が欲しい。というかそれが一番大事だと思う。端的な紹介文はこれが「何であるか」だけでなく「何でないか」も表現し得るので、方向性を定めやすい。

あとはリファレンスと使用例。例は具体的な利用場面も想定できるとなお良し。

実装コードを書いてから気付く（あるいは単純に思い出す）事もあるので、最初に作った仕様を厳守するというわけじゃないです。

あと十分に先が見えていないと最終形を定める事はできず、こういう形で作業を進めるのは無理ですね。そういうときは適当にそれっぽいものを作って、触って、捨てて作り直して、を繰り返す。新しい何かを作るときはそうなりがちだと思う。

ただ、思想については曲げずに進めたいなと。

言うほど毎回しっかりやってるわけでもないんだけど……。理想的な働き方みたいなもの。