保守開発をやっているとフロントエンド開発でも設計書を書いておいて欲しいよな、と相変わらず思う。ただ、小規模なチームやプロジェクトで開発する場合に仰々しい設計書を作るのは重荷となる。1 メンテナンスも辛い。1、2人規模だとテキストベースの設計書すら書く余裕がなかったりする。
そのような場合、Issueやチケット（RedmineやBacklog）を設計書代わりにすると良いのではないか？ Issueやチケット（以降Issue表記とする）は「どんなタスクを行うか」を記載するのだから、機能開発時は「どんな機能を作るか」を記載する場であるはず。そこに詳しく仕様を記載しておけば、後から見返したときにいつ、どんな機能を開発したのか記録を残すことができる。設計書はメンテされず古い情報が混ざるのが問題となるが、開発時にIssueを手厚く記載しておけば「そのとき」の変更点とコードがしっかりと紐付けできるのも良い。
Issueのリンクをコミットメッセージに入れておけば、コードとIssueを紐づけることも簡単にできる。GitHubやGitLabのIssueを使っていればコミットメッセージに #issue番号と書くだけで終わる。
何を書くか？
タイトルに機能名や概要を入れ、機能概要を記載する。自分は下記テンプレートに則って記載することが多い。
## 機能概要 どんな機能かを書く。デザインカンプのスクリーンショットやリンクを貼る。 ## 目的 なぜこの機能が必要なのか、背景を書く。 議論などをした経緯があれば、その議事やチャットのリンクを貼っておく。 ## 機能詳細 ステータスに応じたUI制御やバリデーションなどがあれば書く。 ## 処理設計 処理方式の概要を書く。Issueコメントの上リンクを貼ることが多い。 ## クローズ要件 何が終わったらクローズできるかタスクリスト化して記載する。
特に目的はあった方が良い。時間が経ったときやメンバー交代時に「なぜこの機能が必要なのか」の知見がごっそりと抜けてしまうことが多いため。目的がわからないと「改修しても良いのか」判断ができず、リファクタリングや機能改修・追加時に手も足も出なくなってしまう。
処理設計を説明部分に書いてしまうと1つのコメントが長くなって読みづらい。処理方式は別コメントに詳細を記載し、一番最初のコメントにリンクを貼るのがおすすめ。
また、開発途中で仕様が変わった場合はきちんと最初のコメントに書き戻すことも重要。結局どうなったのか把握するのに1から10まで読まなければいけないのは辛い。スクロールなしである程度概要が把握できるようにしておくとよい。
このようにIssueに詳細を記載すれば、機能一覧表を作るだけである程度の仕様が把握できる。一覧表と言っても大したものではなくて、機能名とIssueリンクを表にしておくだけで充分。機能にアップデートがあればIssueリンクを入れ替えるなどすれば良い。
| 機能名 | Issueリンク |
|---|---|
| XXX | リンク |
リソースが少ないのであれば、特定箇所に情報を集約するのは戦略としてアリではないか。
-
Excelは論外。表計算ソフトでは表を書いて欲しい。↩
