設計作業をするときにクラス図を描くことがあるのですが、そのときに個人的に気をつけているコツがあり、ノウハウの共有のためにそのコツをここにまとめます。
<h2 id="%E8%83%8C%E6%99%AF%E3%83%BB%E5%89%8D%E6%8F%90" data-line="2" class="code-line">
<a class="header-anchor-link" href="#%E8%83%8C%E6%99%AF%E3%83%BB%E5%89%8D%E6%8F%90" aria-hidden="true"></a> 背景・前提</h2>
<ul data-line="4" class="code-line">
<li data-line="4" class="code-line">仕事の設計作業の一環でクラス図を作成するタイミングが何度もある</li>
<li data-line="5" class="code-line">クラス図を描くことの目的は
<ul data-line="6" class="code-line">
<li data-line="6" class="code-line">リーダーや承認者に向けた説明資料ないしエビデンス</li>
<li data-line="7" class="code-line">開発担当に向けた指示資料</li>
<li data-line="8" class="code-line">後生に向けた、設計を素早く把握できるようにするための補助資料</li>
</ul>
</li>
<li data-line="9" class="code-line">APIやバッチ単位などで設計をすることが多い</li>
<li data-line="10" class="code-line">レイヤードアーキテクチャに則った設計で考えている</li>
<li data-line="11" class="code-line">設計中の段階ではクラス図の内容がまだ固まりきらず修正が入ることが度々あるので、手早く手直しできるようにしておきたい</li>
</ul>
<h2 id="%E3%82%B5%E3%83%B3%E3%83%97%E3%83%AB" data-line="13" class="code-line">
<a class="header-anchor-link" href="#%E3%82%B5%E3%83%B3%E3%83%97%E3%83%AB" aria-hidden="true"></a> サンプル</h2>
PlantUMLで生成した画像 
<img src="https://res.cloudinary.com/zenn/image/fetch/s--Pasukjjr--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_1200/https://storage.googleapis.com/zenn-user-upload/deployed-images/bc497092c7252c124fe8e286.png%3Fsha%3Dadca1b9100f97a3afca9235ed78a43846e471519" alt="class diagram" loading="lazy" class="md-img">
コード
<div class="code-block-container"><pre class="language-plantuml"><code class="language-plantuml code-line" data-line="20">title: ユーザ申込API

skinparam class {
 BackgroundColor&lt;&lt;API&gt;&gt; LightSkyBlue
 BackgroundColor&lt;&lt;Batch&gt;&gt; LightGreen
 BackgroundColor&lt;&lt;Service&gt;&gt; LightSalmon
 BackgroundColor&lt;&lt;Repository&gt;&gt; Plum
}

interface EngagementRepository as "契約Repository\nEngagementRepository" &lt;&lt;Repository&gt;&gt;
interface UserRepository as "ユーザRepository\nUserRepository" &lt;&lt;Repository&gt;&gt;

class UserReferService as "ユーザ参照Service\nUserReferService" &lt;&lt;Service&gt;&gt;
 UserReferService ----&gt; UserRepository: 検索
 UserReferService ----&gt; EngagementRepository: 検索
class UserOrderCheckService as "ユーザ申込判定Service\nUserOrderCheckService" &lt;&lt;Service&gt;&gt;
class UserOrderService as "ユーザ申込Service\nUserOrderService" &lt;&lt;Service&gt;&gt;
 UserOrderService --&gt; UserRepository: 新規作成\n更新
 UserOrderService --&gt; UserReferService: ユーザ情報取得
 UserOrderService --&gt; UserOrderCheckService: 新規申込可否判定\n継続申込可否判定
 UserOrderService --&gt; EngagementRepository: 新規契約\n解約

class UserOrderApi as "ユーザ申込API\nUserOrderApi" &lt;&lt;API&gt;&gt;
 UserOrderApi ----&gt; UserOrderService: ユーザ申込
</code></pre></div><h2 id="%E3%82%B3%E3%83%84" data-line="47" class="code-line">
<a class="header-anchor-link" href="#%E3%82%B3%E3%83%84" aria-hidden="true"></a> コツ</h2>
<ul data-line="49" class="code-line">
<li data-line="49" class="code-line">原則として、詳しく描きすぎないこと
<ul data-line="50" class="code-line">
<li data-line="50" class="code-line">クラス図の目的としては今回はあくまでドキュメント用</li>
<li data-line="51" class="code-line">実装に任せる部分は任せる。例えば上記ではメソッド名の指示は避けている</li>
<li data-line="52" class="code-line">ただ一方で、実装クラス名を指示したいときには、上記の図のように併記をしておくとよい</li>
<li data-line="53" class="code-line">依存関係を全て厳密に書き下すと図が大きく複雑になってしまうことがある。改修などがある主要なものだけ抜き出す</li>
</ul>
</li>
<li data-line="54" class="code-line">コード上の工夫
<ul data-line="55" class="code-line">
<li data-line="55" class="code-line">コードでは図とは逆に下層から上層に向けた順番で書いていく。直感的ではないが、PlantUMLの仕様上こうするしかなさそう</li>
<li data-line="56" class="code-line">ジェネリクスと <code>skinparam</code> を活用しつつ、レイヤーを色分けする</li>
<li data-line="57" class="code-line">同一レイヤーでは <code>--&gt;</code> で、レイヤーを跨ぐ場合には <code>----&gt;</code> で繋ぐと、レイヤーの間隔がほどよくなる</li>
<li data-line="58" class="code-line">クラス名をそのままノード名に使うと楽</li>
</ul>
</li>
<li data-line="59" class="code-line">ひとつのAPIもしくはバッチに対して今回のようなクラス図をひとつ、という単位で描いている
<ul data-line="60" class="code-line">
<li data-line="60" class="code-line">ひとつの図に複数入れようとすると複雑さが上がってしまう</li>
</ul>
</li>
</ul>
<h2 id="%E8%A3%9C%E8%B6%B3%E6%83%85%E5%A0%B1" data-line="62" class="code-line">
<a class="header-anchor-link" href="#%E8%A3%9C%E8%B6%B3%E6%83%85%E5%A0%B1" aria-hidden="true"></a> 補足情報</h2>
<ul data-line="64" class="code-line">
<li data-line="64" class="code-line">PlantUMLは何を使って書いてる？
<ul data-line="65" class="code-line">
<li data-line="65" class="code-line">vscodeか<a href="https://obsidian.md/" target="_blank" rel="nofollow noopener noreferrer">Obsidian</a>。どちらもPlantUMLのPluginを追加して使っている</li>
<li data-line="66" class="code-line">ただし、外部サーバにデータを送信することを避けるために、ローカルサーバを立てて使うようにしている</li>
<li data-line="67" class="code-line">具体的にはPlantUML PicoWeb Serverを使っている: <a href="https://plantuml.com/ja/picoweb" target="_blank" rel="nofollow noopener noreferrer">plantuml.com/ja/picoweb</a>
</li>
<li data-line="68" class="code-line">docker でもできるらしい: <a href="https://hub.docker.com/r/plantuml/plantuml-server" target="_blank" rel="nofollow noopener noreferrer">plantuml/plantuml-server - Docker Image | Docker Hub</a>
</li>
</ul>
</li>
<li data-line="69" class="code-line">Mermaidでも同様の図を作成できる？
<ul data-line="70" class="code-line">
<li data-line="70" class="code-line">ジェネリクスに相当するものがなかった気がする。色分けを再現するのが難しいかも。色でなくノードの形で代用するという方法は考えられそう</li>
<li data-line="71" class="code-line">ノードの配置や矢印の長さをいい感じに整えるのがMermaidだと難しそう</li>
</ul>
</li>
</ul>

PlantUMLでクラス図を描くときのコツ

Discussion