設計ドキュメントとソースコードについて思うこと
こんにちは。 Esperna - Qiita です。 私は組み込みLinux製品の開発を行なっています。 今年は錠制御に関わるシステムを主にnodeJSで開発していました。
前回はE2Eテストについて書きましたが 今回は設計ドキュメントとソースコードについて思うことについて書きます。 「ソースコードは設計書であり、プログラミングが設計作業である」という意見について、私は正しいと思っています。 一方で、開発をスケールさせていくことを考えると、一定設計ドキュメントを残すべきではないかとも思っています。
今回、設計ドキュメントとソースコードという観点でみた時に 自分のこの一年の開発はどうだったのか？振り返ってみました。 開発としては設計ドキュメントを残し、設計と実装のトレーサビリティを取る開発をしていました。
ここでいう設計ドキュメントとは具体的にクラス図、状態遷移図、シーケンス図を指します。
よかった点
- 不具合があった時にこのクラス図（あるいはシーケンス図）のここを直せば良いということをチームメンバに伝えやすい
- 複数人で設計の妥当性を議論する際に、クラス図（あるいはシーケンス図、状態遷移図）があるとチーム内で認識を合わせる際の助けとなる
- これらの図がない状態で議論をすると、各人の認識にズレが生じやすいことがあるように思われる
- 個人が作業する上での外部記憶として便利である
- 個人のスキルや脳内記憶容量にもよりますが一定の規模より大きい設計になると、クラス図（あるいはシーケンス図、状態遷移図）があった方が設計・プログラミングをし易いと思われる
- 一定の規模より大きくなったら分割してイテレーションを回すのがセオリーだが結局全部の要素の組み合わせを考えなければ設計できないこともあるように思われる
- 後になって書かなければいけないという理由で、設計書を書くという作業（単体テストを後から書いてカバレッジだけ通すような作業）がなかった
- 設計を行う過程のアウトプットとして書くことができた
- 時間をかけて設計した分、設計そのものがひっくり返るような大きな手戻りはなかった
- 成果物がdocやspread sheetではなくplantumlでgithubを使って、バージョン管理とPRで運用できたのはよかった
悪かった点
- 実装に近いレベルでシーケンス図を書いてしまうとちょっとした変更で設計ドキュメントのメンテナンスコストが発生した
- もう少し抽象度を上げたシーケンス図にすべきだった
- ドキュメントが多いと他者がドキュメントを探す・理解するのに時間がかかった
- これはドキュメントの整理の仕方に改善の余地があることを示唆していると思われる
- 設計ドキュメントを書くことに時間をかけるよりも、ある程度の時点で実装して動かしてみることで別の視点に気づけると思われる部分もあった
- モジュール境界のI/Fを説明するドキュメントが足りないと感じた
- これは個人のこだわりに近い部分があるかもしれないがgodocのようなドキュメントを残したかった
- モジュール境界のI/Fにこだわるのは前述のE2Eテストを補強するため
今後について
開発をスケールさせていくことを考え、皆が一定設計ドキュメントを残すということを考えると、 要求が比較的固定的なプロジェクトでは、以下に絞ってドキュメントを残すのは一定意味があるのではと思いました。
- モジュール境界のI/F
- クラスの責務分担
- 主要なシナリオレベルのシーケンス図（必要なら状態遷移図）
株式会社フォトシンスでは、一緒にプロダクトを成長させる様々なレイヤのエンジニアを募集しています。 photosynth.co.jp
Akerunにご興味のある方はこちらから akerun.com
