2ヶ月ほど前にこんなエントリを書いた。
「実際どのような内容が書いてあれば保守する人が困らないのかな」とずっと考えたのだが、あまり良い考えが浮かばなかった。モヤモヤしてるので、洗い出してみる。
あると嬉しい：画面表示に必要なAPIに関する情報
- 利用API
- 呼び出しタイミング
- HTTPメソッド
- 利用パラメータ
- API利用における制限があれば記載
- 外部APIだと1hに〇〇回までとかある
大半のWebアプリケーションは外部（DBやストレージetc...）からデータを持ってきて表示している。バックエンド領域で処理をかけてUIで綺麗に画面表示…とするやり方はよくある。このときに使うAPI情報は設計ドキュメントがないと保守しづらい。
設計書に画面でどんなAPIを使っていて、どこに何のパラメータを使うか記述があれば、設計書をみるだけである程度仕様を推測できる。ドキュメントがないと利用APIの仕様把握から実施する必要があってつらい。
単体テストを書けば〜とも思うのだが、API通信が挟まる領域にテストを書こうとするとモックのセットアップで躓きやすい印象がある。あと、テストではAPIの利用制限やいつ呼び出すか（呼び出し順序）は表現できない。簡単で良いので処理の概要くらいはドキュメントを残して欲しかったなと思うことが多かった。
あると嬉しい：バリデーションロジック
- フォームバリデーション
- バリデーションNGだった場合のUI仕様
- エラーメッセージは何を出すか
- ボタン制御かけるか
特に入力間違いが許されないタイプのWebアプリケーションな場合、仕様が残ってないとデグレしたときに気づけない。仕様バグ → 影響でる → 謝るの流れができると色々と大変なことになる。設計書がないとこの調査に時間がかかるので、手がかりが欲しいなと思った。
単体テストがあればドキュメントは不要。ただ、画面作成前に何かしらで仕様レビューはするはず。口頭で済ませずにテキストを残して欲しい。issueやチケットに書くならPull Requestに「バリデーション仕様はこれ！」とか書いて欲しい。情報が何もない、が最悪。
まだあるんだけどうまく文章にならないな〜
