最近は設計をする際にできる限り API 仕様を正確に記述するようにしている。このことを意識し始めた大きな要因は主に次の 2 つだと思う。
1 つ目は以前、前職で働いているときに柴田さんに API 仕様の重要性を教えてもらったことから。この時に聞いたことは以下のブログ記事にまとまっているのでぜひ読んでほしい。
もう 1 つは、今年の頭に読み終えた A Philosophy of Software Design から。この本では、複雑さを減らすために API の仕様が限りなくシンプルで、多くの機能を提供する deep module を目指すべき、といったことが言及されている。
Go ではドキュメントシステムとして GoDoc が提供されているため、上記のような洗練された正確なインターフェースを記述するためにこれを開発時に利用している。 ローカルホストで GoDoc を起動しておいて、新しい型や関数、変数が追加されるたびに十分なコメントや Example テストを書いて GoDoc でセルフレビューしている。 GoDoc は、エクスポートされた要素のコメントのみをドキュメント化するため、客観的に API 仕様を見ることができ、その結果不必要にエクスポートされている要素や仕様漏れを探しやすい。
10 月から 3 月までは働いていなかったため、この開発スタイルを使っていたのは自作 OSS のみだった。具体的には以下の Go プロジェクト。
dept はコマンドだけど、main パッケージが依存するパッケージのドキュメントはライブラリと同じようにしっかり書いている。
本当は GitHub で Pull Request をつくるときにも変更を元に生成したドキュメントを見れるようにしてレビューできるようにしたいけど、あまり良い方法が思いつかないのでできていない。いずれ何かの仕組みをつくってやっていきたいと思っている。
