Dokumentieren Ihrer Codeflüsse mit Mermaid

Abgeschlossen

Neben dem Schreiben von Text oder Code sind polyglotte Notebooks in der Lage, Mermaid-Diagramme zu rendern.

Mermaid ist eine Sprache, mit der Sie verschiedene Arten von Graphen und Diagrammen mithilfe von Text ausdrücken können. Polyglotte Notebooks können für Mermaid geschriebenen Code annehmen und rendern. Ein guter Anwendungsfall besteht darin, zu zeigen, wie Ihr Code funktioniert.

Bearbeiten wir ein Beispiel, das einen Flow beim Kauf dokumentiert.

Stellen Sie sich vor, Sie möchten dokumentieren, wie Ihre API funktioniert, wenn eine Zahlung aus einem Kauf verarbeitet wird. Hier sehen Sie den Mermaid-Code aus einer Methode für den Auftragsabschluss, bei der der Code schrittweise über verschiedene Ebenen aufgerufen wird:

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);
        }
    }
}

Sie möchten schnell über ein visuelles Objekt zeigen, wie dieser Code funktioniert. Also verwenden Sie einen Mermaid-Code wie diesen:

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

Wenn Sie den Mermaid-Code schließlich in eine Codezelle einfügen, erhalten Sie ein schönes Rendering wie dieses:

Das obige Bild aus dem Mermaid-Rendering ist auf den ersten Blick leichter zu verstehen. Sie können es auch an nicht technische Beteiligte weitergeben, um zu zeigen, wie das System funktioniert.