Mermaid を使ってコード フローを文書化する

  • 5 分

多言語ノートブックは、テキストやコードの記述以外に、Mermaid ダイアグラムのレンダリングができます。

Mermaid は、テキストを使用してさまざまな種類のグラフやダイアグラムを表現できる言語です。 多言語ノートブックは、Mermaid 用に記述されたコードを受け取り、レンダリングすることができます。 適切なユース ケースは、コードのしくみを示すことです。

購入フローを文書化する例に取り組んでみましょう。

購入の支払いが処理されるときの API のしくみを文書化するとします。 さまざまなレイヤーのステップでコードが呼び出される精算メソッドの Mermaid コードを次に示します。

class CheckoutService {
    private \_cart;
    private \_cardService;
    private \_shippingService;

    public CheckoutService(
        Cart cart,
        CardService cardService,
        ShippingService shippingService) {
        this.\_cart = cart;
        this.\_cardService = cardService;
        this.\_shippingService = shippingService;
    }

    public void Checkout() {
        if(this.\_cart.GetTotal() > 0) {
            let responseCode = this.\_cardService.Charge(new Card("Visa", "1234"));

            if (responseCode != 200) {
                throw new Exception("Unable to charge card");
            }
        
            this.\_shippingService.Ship("123 Main St", this.\_cart);
        }
    }
}

このコードがどのように動作するかをビジュアルで素早く示す必要があるため、次のような Mermaid コードを使用します。

sequenceDiagram
    CheckoutService ->> CardService: Charge(card)
    CardService -->> CheckoutService: OK, payment cleared
    CheckoutService -) ShippingService: Ship(cart)
    ShippingService -->> CheckoutService: OK, "shipping cart content"

最終的に、Mermaid コードをコード セルに挿入することで、次のような適切なレンダリングが得られます。

人魚コードを Polyglot Notebook コード セルに配置してレンダリングされたビジュアルのスクリーンショット。

Mermaid レンダリングの上記のビジュアルは、一目でわかりやすく、非技術関係者と共有して、システムのしくみを示すこともできます。