Edited at

設計ドキュメント(UML)をPlantUMLで書いてみる


はじめに

先日こちらでScrum Inc.認定スクラムマスターを取得しました。

Scrumとドキュメントというと、「Scrumではドキュメントなんかいらないんだよ」と捉えている方も多いと思いますが、実はちょっとニュアンスは違うと思います。

Scrumでは「無駄なドキュメントは書かない」「ドキュメントよりも動くモノを重視しよう」と言っているだけでドキュメントが必要ないとは言っていないようです。

例えば開発の初期ステージでUML図を書くことによって、設計に対するチーム全員の理解度が高まるのであればそれは有効なドキュメントであるかも知れません。

個人的には、できれば基本設計のドキュメントはチームメンバーで共有しておいた方が良いと思います。基本設計とは、チームで作成する、システム全体のルールと言い換えても良いと思います。これを共有できなければルール違反者が続出することになります。

スクラムマスターとしては、このような障害は速やかに排除しなければなりません。

ただし、ドキュメントを書くために膨大な時間を費やすことはしたくありません。またドキュメントは必ずメンテナンスが必要で、新規に書くことよりもこれを保守することの方が難しいものです。

長々と書きましたが、要するにPlantUMLで書けばドキュメントも比較的短時間に書け、必要であればメンテナンスも容易なのではないかと考えています。


PlantUML とは

PlantUML は、UML、またはUML以外の図をテキストで記述するためのオープンソースのツールです。

下記のような図を書くことができます。

記述がテキストであることから、GitHubなどのリポジトリーで管理するのに適しています。

これはドキュメントの保守性から言ってとても重要です。

また、既存のファイルからテキストでコピー&ペーストがし易いことから、同じような設計書を書く場合に効率が高そうです。


この記事の目標

基本設計書では特にクラス図とシーケンス図での記述が重要と考えています。

またER図も書けるようなので、後日これにチャレンジしてみます。


  • UMLクラス図を書く

  • UMLシーケンス図を書く


環境


  • MacOS Mojave(10.14.6)

  • VSCode 1.36.1

  • PlantUML

  • graphviz


インストール


Homebrew インストール

まずは、Homebrewが必要です。ターミナルで下のようにコマンドを実行してHomebrewをインストールしてください。

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

使い方はこちらにも記載しています。


VSCode インストール

https://code.visualstudio.com

Homebrewまたは上記のサイトから取得したインストーラ

を使ってVSCodeをインストールします。

Homebrewでは以下のようなコマンドを実行します。

$ brew cask install visual-studio-code

または、https://code.visualstudio.com/download からインストーラをダウンロードして実行します。

VSCodeには拡張機能をインストールする機能があり、UML、ER図を書くことができるPlantUMLもその内の一つです。

VSCodeには多くの拡張機能がありますので、下記記事などを参考にして便利な拡張機能を入れると良いと思います。リストにはもちろんPlantUMLも含まれています。

VSCodeのオススメ拡張機能 24 選 (とTipsをいくつか)

VSCodeの拡張機能 おすすめ(8/14更新)


Java をインストールする

PlantUMLの実行にはJavaが必要になります。しかしながらOracle Java SEの無償サポートは終了しましたので、無償利用の場合は、

https://www.oracle.com/technetwork/java/javase/downloads/index.html

こちらのOracleJDKではなく

⭕️ https://jdk.java.net

こちらのOpenJDKを利用します。(個人利用の場合はOracleJDKでも大丈夫です。商用は❌)

2019/8/4現時点では、最新版はJDK12です。こちらはOracleJDKと区別するために、OpenJDKと呼ばれていますが、キャプチャー画面左下を見るとわかるように、やはりOracleが主導して提供されている無償のJDKになります。

ただし、上記サイトからダウンロードするとインストーラがなくて面倒なので、brewを使ってインストールします(結局brew・・・)

$ brew cask install java

バージョンなどを確かめてみます。

$ java -version

openjdk version "12.0.1" 2019-04-16
OpenJDK Runtime Environment (build 12.0.1+12)
OpenJDK 64-Bit Server VM (build 12.0.1+12, mixed mode, sharing)


graphviz をインストールする

https://www.graphviz.org

PlantUMLは、シーケンス図とアクティビティ図以外は DOTを使うらしいので図を描画させるためには、Graphvizが必要になるそうです。 → 参考ページ

brew install graphviz


PlantUML をインストールする

VSCodeで、⌘+Pを押し、出てくるテキストフィールド内で ext install plantumlと入力します。

一番上がPlantUMLです。


書き方

ファイル名は、filename.pumlとします。filename.puでも大丈夫です。

下記のように <|-- を使うと継承関係が記述できます。

@startuml

哺乳類 <|-- ねこ
哺乳類 <|-- ひと

哺乳類 : 年齢
哺乳類 : 体重
哺乳類 : 食べる()
哺乳類 : 歩く()
哺乳類 : 眠る()

ねこ : 鳴く()
ねこ : じゃれる()

ひと : 住所
ひと : 電話番号
ひと : 働く()

@enduml

option+Dでプレビューできます。

上のファイルは、下記のようなUMLを生成するメニューで作成しています。

その他にもコンポジット、集約の関係も記述できます。

詳しくはこちら

http://plantuml.com/ja/class-diagram

@startuml

人 o-- "0..*" 車 : 集約

車 "1" *-- "1" ハンドル : コンポジット
車 "1" *-- "1" エンジン : コンポジット

@enduml

次に少し複雑なシーケンス図を描いてみます。

@startuml

actor User
box "View" #EEEEBB
participant AppDelegate
participant TopView
end box

box "ViewModel" #BBBBEE
participant LonginViewModel
end box

box "Model" #DDBBDD
participant LoginUseCase
participant LoginRepository
end box

participant EndPoint

activate EndPoint #FFBBBB

User -> AppDelegate : 起動

activate AppDelegate #FFBBBB

AppDelegate -> TopView : アクティベート
activate TopView #FFBBBB

note over TopView
画面遷移管理
end note

TopView -> LonginViewModel : ログイン可否確認
activate LonginViewModel #FFBBBB

LonginViewModel -> LoginUseCase : Token有無問い合わせ
activate LoginUseCase #FFBBBB

note over LoginUseCase
Tokenの管理
end note

LoginUseCase -> LoginUseCase : Token取得
note left
Tokenはメモリー上に保存とする
end note

alt Token有

LonginViewModel <<-- LoginUseCase : Token有
LonginViewModel -> LoginRepository : Tokenのリフレッシュ要求
activate LoginRepository #FFBBBB
LoginRepository -> EndPoint : Tokenのリフレッシュ要求
else Token無
note over TopView, EndPoint
サインアップ処理
end note

LonginViewModel <<-- LoginUseCase : Token無
TopView <<-- LonginViewModel : サインアップ要求
TopView -> TopView : 初回起動画面表示

TopView <<-- LonginViewModel : サインアップ完了
end

@enduml

なかなか本格的に記述できることがわかります。


Markdownファイル中に挿入する

設計書を書くと言う観点から考えると、当然マークダウンで書きたいと思うのは当然です。

VSCodeでは、マークダウンファイルにPlantUMLのファイルを埋め込んだものもプレビューできます。

# 設計書です

## はじめに
これはテスト文書です。

@import "test.puml"

このように表示されます。


Markdown Preview Enhanced をインストールする

このようなマークダウンファイルをプレビューするには、Markdown Preview Enhancedという拡張機能をインストールします。例によって、⌘+Pを押下し、ext install Markdown Preview Enhancedとします。


おわり