Help us understand the problem. What is going on with this article?

設計ドキュメント(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 インストール

スクリーンショット 2019-08-04 23.43.52.png

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

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

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

VSCode インストール

https://code.visualstudio.com
スクリーンショット 2019-08-04 23.45.03.png

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になります。

スクリーンショット 2019-08-04 23.42.35.png

ただし、上記サイトからダウンロードするとインストーラがなくて面倒なので、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と入力します。

スクリーンショット 2019-08-05 1.35.43.png

一番上がPlantUMLです。

書き方

ファイル名は、filename.pumlとします。filename.puでも大丈夫です。
下記のように <|-- を使うと継承関係が記述できます。

@startuml

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

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

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

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

@enduml

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

honyuurui-neko-hito

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

スクリーンショット 2019-08-05 23.49.13.png

その他にもコンポジション、集約の関係も記述できます。
詳しくはこちら
http://plantuml.com/ja/class-diagram

@startuml

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

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

@enduml

class-composit

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

@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

seq_login

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

Markdownファイル中に挿入する

設計書を書くと言う観点から考えると、当然マークダウンで書きたいと思うのは当然です。
VSCodeでは、マークダウンファイルにPlantUMLのファイルを埋め込んだものもプレビューできます。

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

@import "test.puml"

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

スクリーンショット 2019-08-06 0.10.11.png

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

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

スクリーンショット 2019-08-06 0.11.47.png

おわり

BlueEventHorizon
⚔️ios engineer ❤️science fiction 💚XCode 🌲innovation and entrepreneurship 🏃‍♂️golang beginner
https://note.mu/k2moons
yumemi
みんなが知ってるあのサービス、実はゆめみが作ってます。スマホアプリ/Webサービスの企画・UX/UI設計、開発運用。Swift, Kotlin, PHP, Vue.js, React.js, Node.js, AWS等エンジニア・クリエイターの会社です。Twitterで情報配信中https://twitter.com/yumemiinc
http://www.yumemi.co.jp
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away