概要
目的
「構造化された見やすいドキュメント」と
「表現が一定水準に統一された図（UML）」を
テキストファイルだけで記述したい！
理由
・テキストファイルは（色んな意味で）軽い
・修正の履歴が管理しやすい
手段
構造化された見やすいドキュメントは「markdown」
表現が一定水準に統一された図（UML）は「PlantUML」で記述する。
動作環境
Visual Studio Code上に、MarkdownとPlantUMLが書ける環境を準備する。
参考Webサイト
インストールはこの辺
VS Code で UML を描こう！
VS Code + MarkDown + PlantUML で開発ドキュメントをわかりやすくする
さらに細かく
PlantUML Cheat Sheet
VSCode拡張のPlantUMLプレビューが表示されない場合の対応
VSCodeにPlantUMLを導入する手順
VS CodeにPlantUMLを導入して業務効率化を図る
Visual Studio Codeで自由自在にUMLを描こう
Visual Studio CodeでPlantUMLを使うメモ (Windows編).md
PlantUMLの環境を設定する
VSCodeのMarkdown Preview EnhancedでPlantUMLが描画されない
以下、Markdown + PlantUMLによるドキュメントの凡例
ドキュメント概要
Readme
外部仕様
外部仕様を記述します。
プロトコル
内部仕様
設計
状態遷移図
状態遷移図は、実際に、Visual Studio Code上にて、
PlantUMLに対応したプレビュー画面にて以下のように描画されます。
シナリオ
- ターゲットは？
- どのような状況で使うのか？
- どのように使うのか？
- 制約事項は何か？
対象外
- 明らかにオーバースペックなこと
- 今のバージョンでやらないこと
- 対象外のプラットフォーム
用語解説
- 一般的な用語でもドキュメント中での意味を書く
未解決の問題
- 何が未解決か残す
- これが残っているうちはプログラマーにコードを書かせない（気持ちを持つ）
UMLの指針
以下を駆使する。
- 状態遷移図
- シーケンス図
- ユースケース図
- クラス（ブロック）図
- 配置図
- タイミング図
全体的な書き方に関する指針
- 一覧性が重要（カラフルな表だと割と見やすい）
- 全体像を把握させる（図表でシンプルに表現できる仕様／設計であるべき）
- フローチャート(PlantUMLのアクティビティ図)も駆使する
- 他の仕様や設計との関係性を意識する
- 想定される状況をすべて書く
- 何がエラーになるかすべて書く
- 全てのエラーに対してどう処理するか書く
- 何故、そのような振る舞いに至ったかの経緯や思考実験の経過を書く
- シンプルなプログラムにする事が可能な仕様／設計であるのが望ましい
- テストケースが容易に洗い出せるのが望ましい
- テスト可能な仕様／設計でないといけない
- テスト再現性が高い（テストし易い）仕様／設計であることが望ましい
- ソースコード読めば一目瞭然の事は書くべきではない
- ソースコードがさくさく読めるためのガイドとなる事を目指すべき