Kódfolyamatok dokumentálása a Hableány használatával

Befejeződött

A Szöveg vagy kód írása mellett a Polyglot Notebooks képes a Hableány-diagramok megjelenítésére.

A Hableány egy olyan nyelv, amellyel különböző típusú diagramokat és diagramokat fejezhet ki szöveg használatával. A Polyglot Notebooks képes átvenni a Hableányhoz írt kódot, és renderelni. Jó felhasználási eset a kód működésének szemléltetésére.

Dolgozzunk egy olyan példán, amely egy vásárlási folyamatot dokumentál.

Tegyük fel, hogy dokumentálni szeretné az API működését, amikor egy vásárlásból származó fizetést dolgoznak fel. Íme a Hableány-kód egy olyan kivételi módszerből, amelyben a kód különböző rétegeken keresztüli lépésekben hívódik meg:

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

Gyorsan meg szeretné jeleníteni a vizualizáción, hogyan működik ez a kód, ezért a Következőhöz hasonló Hableány-kódot használ:

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

Végül, ha a Hableány-kódot egy kódcellába helyezi, az alábbihoz hasonló szép renderelést kap:

A Hableány-renderelés előző vizualizációja első pillantásra könnyebben érthető, és a nem műszaki érdekelt felekkel is megoszthatja, hogy bemutassuk a rendszer működését.