More than 3 years have passed since last update.

ドキュメントをテキストファイルで記述する方針メモ

Last updated at 2020-01-15Posted at 2019-08-07

概要

目的

「構造化された見やすいドキュメント」と
「表現が一定水準に統一された図（UML）」を
テキストファイルだけで記述したい！

理由

・テキストファイルは（色んな意味で）軽い
・修正の履歴が管理しやすい

手段

構造化された見やすいドキュメントは「markdown」
表現が一定水準に統一された図（UML）は「PlantUML」で記述する。

動作環境

Visual Studio Code上に、MarkdownとPlantUMLが書ける環境を準備する。

以下、Markdown + PlantUMLによるドキュメントの凡例

ドキュメント概要

Readme

外部仕様

外部仕様を記述します。

プロトコル

内部仕様

設計

状態遷移図

状態遷移図は、実際に、Visual Studio Code上にて、
PlantUMLに対応したプレビュー画面にて以下のように描画されます。

シナリオ

ターゲットは？
どのような状況で使うのか？
どのように使うのか？
制約事項は何か？

対象外

明らかにオーバースペックなこと
今のバージョンでやらないこと
対象外のプラットフォーム

用語解説

一般的な用語でもドキュメント中での意味を書く

未解決の問題

何が未解決か残す
これが残っているうちはプログラマーにコードを書かせない（気持ちを持つ）

UMLの指針

以下を駆使する。

状態遷移図
シーケンス図
ユースケース図
クラス（ブロック）図
配置図
タイミング図

全体的な書き方に関する指針

一覧性が重要（カラフルな表だと割と見やすい）
全体像を把握させる（図表でシンプルに表現できる仕様／設計であるべき）
フローチャート(PlantUMLのアクティビティ図)も駆使する
他の仕様や設計との関係性を意識する
想定される状況をすべて書く
何がエラーになるかすべて書く
全てのエラーに対してどう処理するか書く
何故、そのような振る舞いに至ったかの経緯や思考実験の経過を書く
シンプルなプログラムにする事が可能な仕様／設計であるのが望ましい
テストケースが容易に洗い出せるのが望ましい
テスト可能な仕様／設計でないといけない
テスト再現性が高い（テストし易い）仕様／設計であることが望ましい
ソースコード読めば一目瞭然の事は書くべきではない
ソースコードがさくさく読めるためのガイドとなる事を目指すべき

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up