先日の記事、
「現場に必要なOSS (オープンソースソフトウェア) のテストツールとは」
で触れた、無償のテストツールをいくつか紹介していくシリーズ。
今回は、ソフトウェア設計時に活用できるモデリングツール
『 PlantUML 』
を実際に使ってみました。
本格的なテストフェーズで使える無償の単体テストツール『 Google Test 』を使ってみた記事はコチラ ↓ から。
設計ドキュメントの必要性と実情
みなさんはソフトウェア設計時のドキュメントについて、どのような方法で作成や整備をされていますか？
ソフトウェアの改修が必要な場合に、設計ドキュメントを見返すことに苦労したことはありませんか？
良く聞くところでは…
- 「設計書は作らないので、ソースコードのコメント または ソースコード自体を読んで理解する」
- 「前任者から口頭での説明を受ける」
- 「Excelで設計書を作るが、メンテが不十分で変更前後の差分がわかりにくい(※最新ソースコードが反映されていない)」
などなど。
過去の開発案件などは、自分が作ったソフトウェアでさえも処理の内容を忘れてしまいがちなものですが、
きっとこの記事をご覧のみなさんも、
どんな処理をしているかを、できるだけ容易に時間を掛けずに把握したい
という状況を経験したことがあることでしょう。
また、派生開発をしていくことが予定にあるのであれば、
そのときの効率を考えると、設計ドキュメントを残しておくことは大変重要ですよね。
しかし！
重要性は理解していても、実際の開発中となると、
度重なる変更や修正に追われ、ドキュメント整備は疎かになりがちです。
レビューにおいても、可読性の良いドキュメントが整備されていないと、
変更する開発者にとっても、レビュワーにとっても、
確認に時間が掛かり、ムダな開発コストが増えていき、
- 「開発と並行してドキュメント類も整備し、レビューしたい」
- 「ドキュメントの整備には、あまりコストをかけたくない」
…となるのではないでしょうか。
そこで、これらの悩みを解決できる無償のツール『PlantUML』を使ってみました。
PlantUMLとは
PlantUML(プラントユーエムエル)は、
シンプルで人間が読むことのできるテキストの記述を使って、UMLの図を描く事を目的とした、
名前の通りUML（Unified Modeling Language：統一モデリング言語）を記述するためのツールです。
UMLとはオブジェクト指向の分析、開発向けに統一化が図られたモデリング言語です。
こう書くとPlantUMLはオブジェクト指向言語の開発の方以外は使えない印象がありますが、
「モデリングツールというよりむしろ描画ツールである」と公式のFAQに書かれいます。
UMLベースのテンプレートを元にファジーに書きたいものが書けるツールという感触です。
PlantUMLで取り扱えるテンプレートは以下の通りです。
PlantUMLのココが良い！
PlantUMLを便利だと思う点はいくつもありますが、
特に便利と感じるのは以下の3点です。
- 編集が楽である
特に一度作ったものを再編集するのが楽になります。
通常Excel等をはじめとした図の組み合わせやテンプレートを使う場合、一度作ったものの再編集、例えば順番の変更や処理の差し込み等があった場合、ブロックの差し込みや付随するアロー等の修正などの作業が結構手間に感じる人も多いのではないでしょうか？PlantUMLの場合、テキストの変更だけで図が作れるため、順番の入れ替えや差し込みなどが簡易に済むのでドキュメントの整備・保守といったメンテナンスに時間を掛けずに済みます。 - ソースコードと共に管理がしやすい
管理するものがテキストのみになるため、ソースコードと合わせての管理が非常に楽になります。
特に、SVNやGITといった構成管理ツールはExcel等のバイナリファイルの場合、図などの変更の詳細を把握できないのですが、PlantUMLは単純なテキストの為、差分機能を使って変更内容の詳細を抽出・検知が可能です。そのため、ソースコードの変更に合わせて、適切にドキュメントも修正されているかを逐一チェックしたり、コミット履歴から把握したりできます。 - 対応する図のテンプレートが多く、アップデートも継続されているOSSプロジェクトである
対応しているテンプレートが多く、あらゆる設計ドキュメントをPlantUMLだけでカバーできます。UMLの図だけではなく、最近ではガントチャートやマインドマップも追加されるなど、利用範囲が増えているのも特徴です。サードパーティからの供給も多く、標準ライブラリを利用する事で、AWSやOfficeのアイコンなども利用できるなど、頻繁に機能向上されるツールです。
インストール手順
簡単に試すのであれば、PlantUML Serverを利用するのが最も手軽に利用できる手段です。
公式のオンラインサーバーからブラウザ上で直接触ってみることが可能です。
作成した図の状態は、URLにそのまま反映される仕組みの為、サーバー側に情報を残す事は一切ありません。
ローカル環境に構築する場合は、以下が必要になります。
- Javaのインスト―ル
本体がJavaアプリの為、Javaのインストールが必要です。 - Graphvizのインストール
PlantUML(Javaアプリ)単体では、シーケンス図とアクティビティ図のみの対応です。
先ほど挙げたその他の図に対応するには、Graphvizの別途インストールが必要です。 - PlantUML本体、またはプラグインのインストール
Java本体だけでも利用可能ですが、操作性から何かしらのエディタを用いることをお勧めします。
PlantUMLは、EcllipseやVisualStudioCodeなど様々なエディタ、統合開発環境に対応します。
今回はVisualStudioCode上で利用していますが、プラグインをインストールするだけで簡単に使えます。
VisualStudioCodeでプラグインを検索しインストールを選択するだけで準備完了
そのほかの統合開発環境やエディタでもプラグインが用意されています。
詳細は公式のHPを参照してください。
実際に設計図を作ってみる
VSCodeの場合、ファイルの拡張子は『*.pu』で作成します。
PlantUMLのファイルのお約束として、
@startuml～@enduml
をファイルの先頭と末尾に記述します。
いくつかのテンプレートを使って実際に書いてみましょう。
アクティビティ図
言い換えると、フローチャートのことです。
そのままソースコードに起こせるほどではないですが、近い書き方が可能でテキストをみるだけでも、ある程度の概要把握は可能です。
Excelでこういったフローチャートを書くよりも、処理に近い形での記述が可能です。
また、修正変更についても図の全体調整などの手間がなく見た目にこだわらなければ、手軽に変更できます。
VisualStudioCode等の一部エディタであれば、図をリアルタイムで更新しながら、図とテキストを並行して確認できます。
管理するのは.pu形式のテキストファイルのみなので管理自体も非常に軽量です。
シーケンス図
シーケンス図も記述可能です。
試しにDT10 GPIO4bit接続のドライバの概略を書いてみました。
Excelで似たようなものを記述する場合、矢印の近くにコメントで補足を付けたりしますが、
PlantUMLであれば”：”の後ろにコメントを記述するだけです。
また、上図右側のプレビュー画面内にある、付箋のようなコメント記述も可能です。
例えば、図の青いブロックに新しい処理[enter/exitcritical]を追加する場合、
Excelでは挿入や矢印の付け替えなどが非常に手間になります。
一方、PlantUMLであれば数行テキストで変更するだけで追加可能です。
また、変更前後の比較をレビューする場合、PlantUMLであれば、WinMergeなどの差分ツールでも比較できます。
これはExcelでの管理と違い、
GitやSVNなどに付随する差分チェック機能を使って、ドキュメントの修正が行われているかの内容を確認できます。
そのため、ソースの変更に合わせて適切にドキュメントが更新されているかをレビュワーや管理側でチェックもできます。
使ってみての感想
実際に使ってみて、
ソースコードから設計図が自動で作成・修正されるため、Excelなどと比べて楽に作成できると感じました。
特に一度作ったものに対して、順番を変更したり、新たな手順を差し込んだり、図を入れ替えたりといった再編集においても、
PlantUMLではテキストの修正のみで図の修正までも済んでしまいます。
Excelでは、新しい部分の差し込みや矢印の配線などのレイアウト調整が手間に感じていました。
一方、デメリットとして、アウトプットのカスタマイズに少し慣れが必要な点です。
自動生成である反面、どう記述することで、どのように図式化されるのかをある程度把握しておかないと、
イメージしたアウトプットとは少し違うと感じる場合もありました。
細かい設定による調整も可能ですが、設定方法については日本語の情報が少なかったり、
公式のHPのどこに情報があるのか少し見つけにくい印象です。
見た目を整える必要があるドキュメントに適用する場合は、
事前にPlantUMLの設定を共有したり、ドキュメント毎のベースフォーマットを共有しておくと良いかもしれません。
まとめ
PlantUMLは、テキストベースでの製図が簡単にできて、
構成管理ツール上でソースコードと共に保守・管理がしやすいOSSツールだと思います。
社内向け設計資料のドキュメントとしては十分に使えるレベルであり、Excelに比べて工数短縮も可能です。手
間をあまりかけずにドキュメントを作りたい、プロセス化したいという方は、ぜひ一度使ってみてはいかがでしょうか？
