Dokumentér dine kodeflow med havfrue

Ud over at skrive tekst eller kode kan polyglotnotesbøger gengive havfruediagrammer.

Havfrue er et sprog, der giver dig mulighed for at udtrykke forskellige typer diagrammer og diagrammer ved hjælp af tekst. PolyglotNotesbøger kan tage kode, der er skrevet til Havfrue, og gengive den. En god brugscase er at vise, hvordan din kode fungerer.

Lad os arbejde på et eksempel, der dokumenterer et købsflow.

Forestil dig, at du vil dokumentere, hvordan din API fungerer, når en betaling behandles fra et køb. Her er havfruekoden fra en udtjekningsmetode, hvor kode kaldes i trin gennem forskellige lag:

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

Du vil hurtigt vise en visualisering, hvordan denne kode fungerer, så du kan bruge en havfruekode på følgende måde:

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

Endelig, ved at sætte havfrue kode i en kode celle, får du en dejlig gengivelse sådan:

Den foregående visualisering fra havfruegengivelsen er nemmere at forstå ved første øjekast, og du kan også dele den med ikke-tekniske interessenter for at vise, hvordan systemet fungerer.