Documentați fluxurile de cod cu Sirenă

Pe lângă scrierea de text sau cod, Blocnotesurile Polyglot sunt capabile să redea diagramele sirenă.

Sirena este o limbă care vă permite să exprimați diferite tipuri de diagrame și diagrame utilizând text. Blocnotesurile Polyglot pot lua cod scris pentru Sirenă și reda. Un caz bun de utilizare este să arătați cum funcționează codul dvs.

Să lucrăm la un exemplu care documentează un flux de achiziție.

Imaginați-vă că doriți să documentați modul în care funcționează API-ul atunci când este procesată o plată de la o achiziție. Iată codul sirenei dintr-o metodă de verificare unde codul este apelat în pașii din diverse straturi:

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

Doriți să afișați rapid printr-un element vizual cum funcționează acest cod, astfel încât să utilizați un cod sirenă astfel:

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

În cele din urmă, amplasând codul sirenei într-o celulă de cod, obțineți o redare plăcută astfel:

Elementul vizual precedent din redarea sirenei este mai ușor de înțeles dintr-o singură privire și îl puteți partaja și cu participanții direct interesați netehnici, pentru a arăta cum funcționează sistemul.