Dizajn i specifikacija

Šta učimo ovog semestra (1–5)

Deset predavanja: dva časa teorije i jedan čas dopunske prakse. Danas: poglavlje 3 (označeno). Isti primjer kroz knjigu: DeliveryApp 2.0.

Šta učimo ovog semestra (6–10)

Deset predavanja: dva časa teorije i jedan čas dopunske prakse. Danas je poglavlje 3. Isti primjer kroz knjigu: DeliveryApp 2.0.

Priča za početak

Priča za početak

Literatura

1. I. Sommerville: Software Engineering, 10th ed., Pearson, 2016 (poglavlja 5 i 7).
2. R. S. Pressman, B. R. Maxim: Software Engineering: A Practitioner's Approach, 9th ed., McGraw-Hill, 2019 (dio o modelovanju i dizajnu).
3. M. Fowler: UML Distilled, 3rd ed., Addison-Wesley, 2003; D. Norman: The Design of Everyday Things, Basic Books, 2013.

Zašto ovo poglavlje

U poglavlju 2 organizovali smo tim i napravili plan izdanja DeliveryApp 2.0. Prije nego što tim počne programirati, mora odlučiti kako će proizvod biti građen iznutra i kako će izgledati spolja. To je dizajn. Prvi dio govori o unutrašnjosti: konceptualnom modelu, UML dijagramima i principima objektno orijentiranog dizajna (SOLID). Drugi dio govori o onome što korisnik vidi: prototipu, korisničkom iskustvu i dokumentu u kojem se dizajn zapisuje da bi ga cijeli tim razumio isto.

Riječi ovog poglavlja (1/2)

• Dizajn – odluke o tome kako će proizvod biti građen (iznutra) i kako će se koristiti (spolja), donesene prije programiranja.
• Konceptualni (domenski) model – slika pojmova iz stvarnog svijeta i veza među njima, bez tehničkih detalja.
• UML (Unified Modeling Language) – standardni jezik dijagrama za opis softvera.
• Enkapsulacija – objekat skriva svoje podatke i nudi samo operacije.
• Kompozicija – objekat se sastoji od drugih objekata („ima”), umjesto da od njih nasljeđuje („jeste”).
• SOLID – pet principa objektno orijentiranog dizajna koji olakšavaju promjene.

Riječi ovog poglavlja (2/2)

• Prototip – rana, nepotpuna verzija proizvoda kojom se provjerava ideja.
• Wireframe – crno-bijela skica ekrana koja pokazuje raspored, bez boja i detalja.
• UX (user experience) – korisničko iskustvo: sve što korisnik osjeća i doživljava dok koristi proizvod.
• Heuristika upotrebljivosti – pravilo iskustva po kojem se ocjenjuje sučelje (npr. Nielsenovih deset).
• Tamni obrazac – dizajn koji navodi korisnika na odluku protiv njegovog interesa.
• SDD (software design description) – dokument specifikacije dizajna.

Ciljevi poglavlja

Nakon poglavlja možete:

nacrtati konceptualni model domena i iz njega klasni dijagram; izabrati UML dijagram za dato pitanje (struktura, ponašanje, raspored); objasniti enkapsulaciju, apstrakciju, nasljeđivanje, kompoziciju i polimorfizam; objasniti svaki od pet principa SOLID na primjeru; izabrati nivo vjernosti prototipa; primijeniti Normanove principe i Nielsenove heuristike na ekran; prepoznati tamni obrazac; napisati kratak dokument specifikacije dizajna.

Plan poglavlja – Predavanje 3: dva časa teorije i jedan čas dopunske prakse

3.1 Konceptualno modeliranje

Prije nego što arhitekta nacrta kuću, pita porodicu: „Ko živi ovdje? Šta radite u kući?” Odgovori su riječi: spavaća soba, kuhinja, garaža, radni sto. Tek kad su riječi jasne, crta se plan.

Konceptualni model je takav popis riječi za softver: koji pojmovi postoje u svijetu proizvoda i kako su povezani. U njemu nema baze, ekrana ni programskog jezika. Za DeliveryApp 2.0 pojmovi su: grad, tarifa, restoran, jelo, kupac, narudžba, stavka, dostavljač. Veze: grad ima tarifu; restoran je u gradu; restoran nudi jela; kupac pravi narudžbe; narudžba sadrži stavke; stavka je za jedno jelo; dostavljač vozi narudžbu.

Konceptualni model se crta UML klasnim dijagramom. Uz svaku vezu piše se višestrukost: 1 (tačno jedan), (nula ili više), 1.. (bar jedan), 0..1 (nijedan ili jedan). Puni romb označava kompoziciju: stavka ne postoji bez svoje narudžbe.

classDiagram
    Grad "1" -- "1" Tarifa : ima
    Grad "1" -- "*" Restoran : u gradu
    Restoran "1" -- "*" Jelo : nudi
    Kupac "1" -- "*" Narudzba : pravi
    Narudzba "1" *-- "1..*" Stavka : sadrži
    Stavka "*" --> "1" Jelo : za
    Dostavljac "0..1" -- "*" Narudzba : vozi

3.1 Konceptualno modeliranje

U vlastitom .md fajlu blok počinje sa ``` `mermaid ```, i VS Code ili GitHub ga iscrta.

3.1 Konceptualno modeliranje

Najvažnija novost u odnosu na verziju 1.x je pojam Tarifa. U verziji 1.x pravilo dostave bilo je napisano u kodu (2,00 € do 3 km, 0,50 € po kilometru). Kad se u modelu pojavi pojam „tarifa grada”, svima postaje jasno da je pravilo podatak koji se razlikuje od grada do grada.

Ukratko – 3.1 Konceptualno modeliranje

• Konceptualni model je popis pojmova domena i veza među njima, bez tehnike.
• Crta se klasnim dijagramom s višestrukošću veza.
• U DeliveryApp 2.0 novi pojam Tarifa pokazuje da je pravilo dostave podatak grada, a ne kod.

3.2 UML u službi dizajna

UML je standardni jezik dijagrama za softver. Nastao je 1997. spajanjem metoda trojice autora (Booch, Rumbaugh, Jacobson), a danas ga održava organizacija OMG. Verzija 2.5 ima 14 vrsta dijagrama, ali u praksi se najviše koristi pet:

3.2 UML u službi dizajna

Sekvencijalni dijagram za „Ponovi narudžbu” pokazuje jednu važnu odluku dizajna: nova narudžba ne kopira stare cijene, nego ih ponovo čita iz jelovnika, i ponovo računa dostavu po tarifi grada. Ako se cijena promijenila, kupac to mora vidjeti prije potvrde.

sequenceDiagram
    actor K as Kupac K-01
    participant A as Mobilna aplikacija
    participant S as Servis narudžbi
    participant J as Jelovnik restorana
    participant T as Tarifa grada
    K->>A: dodir "Ponovi narudžbu" (N-1001)
    A->>S: ponovi(N-1001)
    S->>J: da li jela još postoje i koliko koštaju?
    J-->>S: Margarita 9,50 €, Sok 2,50 €
    S->>T: dostava(4,2 km, 21,50 €)
    T-->>S: 3,00 €
    S-->>A: nova narudžba, ukupno 24,50 €
    A-->>K: "Potvrdi 24,50 €?"

3.2 UML u službi dizajna

Ukratko – 3.2 UML u službi dizajna

• UML ima 14 vrsta dijagrama; najčešće se koriste klasni, sekvencijalni, stanja, komponenti i razmještaja.
• Dijagram se bira prema pitanju na koje odgovara.
• Sekvencijalni dijagram „Ponovi narudžbu” otkrio je odluku: cijene se čitaju ponovo, ne kopiraju.

3.3 Objektno orijentirani dizajn

Objektno orijentirano programiranje (OOP) poznajete iz ranijih predmeta. Ovdje nas zanima kako se njegove ideje koriste za dobar dizajn, onaj koji se lako mijenja. Četiri ideje, uz analogiju s automobilom:

3.3 Objektno orijentirani dizajn

Kompozicija prije nasljeđivanja. Prvi prijedlog za tarife u timu DeliveryApp bio je napraviti klase TarifaGradA, TarifaGradB, TarifaGradC, koje nasljeđuju zajedničku klasu. Za tri grada to radi, ali za trideset gradova znači trideset klasa, i svaki novi grad znači novi kod, novi test i novu isporuku. Bolje je rješenje da su sva tri grada ista klasa s različitim podacima:

@dataclass(frozen=True)
class Tarifa:
    """Pravila dostave jednog grada; novi grad je novi red podataka, ne novi kod."""

    grad: str
    osnovna: int            # cijena do uključenih km, u centima
    ukljuceno_km: float
    po_km: int              # za svaki započeti km preko uključenih
    max_km: float
    besplatna_od: int = 3000
    min_narudzba: int = 500

    def dostava(self, km: float, iznos: int) -> int:
        if km < 0 or km > self.max_km:
            raise ValueError("adresa je izvan zone dostave")
        if iznos < self.min_narudzba:
            raise ValueError("iznos je manji od najmanje narudžbe")
        if iznos >= self.besplatna_od:
            return 0
        dodatni_km = math.ceil(max(0, km - self.ukljuceno_km))
        return self.osnovna + self.po_km * dodatni_km


TARIFE = {
    "A": Tarifa("A", osnovna=200, ukljuceno_km=3, po_km=50, max_km=10),
    "B": Tarifa("B", osnovna=200, ukljuceno_km=2, po_km=60, max_km=8),
    "C": Tarifa("C", osnovna=250, ukljuceno_km=3, po_km=50, max_km=12),
}

3.3 Objektno orijentirani dizajn

Isto u C#, gdje record daje nepromjenjiv objekat s podacima:

record Tarifa(string Grad, int Osnovna, double UkljucenoKm, int PoKm, double MaxKm,
              int BesplatnaOd = 3000, int MinNarudzba = 500)
{
    public int Dostava(double km, int iznos)
    {
        if (km < 0 || km > MaxKm)
            throw new ArgumentException("adresa je izvan zone dostave");
        if (iznos < MinNarudzba)
            throw new ArgumentException("iznos je manji od najmanje narudžbe");
        if (iznos >= BesplatnaOd)
            return 0;
        int dodatniKm = (int)Math.Ceiling(Math.Max(0, km - UkljucenoKm));
        return Osnovna + PoKm * dodatniKm;
    }
}

Oba programa (primjeri/python/dostava.py i primjeri/csharp/Dostava.cs) za N-1001 ispisuju dostavu 3,00 € u Gradu A, 3,80 € u Gradu B i 3,50 € u Gradu C.

Ukratko – 3.3 Objektno orijentirani dizajn

• OO dizajn koristi apstrakciju, enkapsulaciju, nasljeđivanje i polimorfizam da bi se kod lakše mijenjao.
• Kompozicija i podaci često su bolji od nasljeđivanja: tri grada su jedna klasa s tri reda podataka.
• Python dataclass i C# record su prirodan način da se napiše objekat koji nosi podatke.

3.4 SOLID: pet principa dobrog dizajna

Robert C. Martin skupio je početkom 2000-ih pet principa objektno orijentiranog dizajna, a prva slova njihovih engleskih imena daju riječ SOLID (čvrst). Svi imaju isti cilj: da promjena na jednom mjestu ne izazove lavinu promjena na drugim.

3.4 SOLID: pet principa dobrog dizajna

Princip D je posebno važan za proizvod. U verziji 1.x DeliveryApp je direktno pozivao jednu firmu za mape. U Gradu B ta firma nema tačne adrese (rizik RZ-1 iz poglavlja 2). Ako kod zavisi od apstrakcije ServisMapa s jednom operacijom udaljenost(od, do), zamjena firme je promjena jedne klase, a ne pola aplikacije.

from typing import Protocol

class ServisMapa(Protocol):
    def udaljenost(self, od: str, do: str) -> float: ...

3.4 SOLID: pet principa dobrog dizajna

interface IServisMapa
{
    double Udaljenost(string od, string doAdrese);
}

3.4 SOLID: pet principa dobrog dizajna

Ukratko – 3.4 SOLID: pet principa dobrog dizajna

• SOLID su pet principa: jedna odgovornost, otvoreno–zatvoreno, zamjena, razdvajanje interfejsa, inverzija zavisnosti.
• Zajednički cilj im je da promjena na jednom mjestu ne izazove lavinu promjena.
• Inverzija zavisnosti omogućava da se servis mapa zamijeni bez mijenjanja ostatka aplikacije.

Provjeri se

1. Šta znači višestrukost 1..* na vezi Narudžba–Stavka? Narudžba ima bar jednu stavku.
2. Koji UML dijagram odgovara na pitanje „ko koga poziva i kojim redom”? Sekvencijalni.
3. Koji princip SOLID kaže da se novi grad dodaje bez izmjene postojećeg koda? Otvoreno–zatvoreno.

Odgovori: tipka R ili klik na zamućeno polje.

3.5 Prototipiranje korisničkog sučelja

Prije nego što se sagradi zgrada, arhitekta napravi maketu. Maketa je jeftina, i na njoj se odmah vidi da je ulaz na pogrešnoj strani. Prototip je maketa softvera: rana verzija koja služi da se ideja provjeri s korisnicima prije nego što se programira.

Prototipovi se razlikuju po vjernosti (koliko liče na pravi proizvod):

3.5 Prototipiranje korisničkog sučelja

3.5 Prototipiranje korisničkog sučelja

Pravilo: što je ideja neizvjesnija, to je prototip jeftiniji. Ena je za „Ponovi narudžbu” napravila tri papirne skice za deset minuta i pokazala ih petorici kupaca u kafiću. Dvojica nisu primijetila dugme na dnu ekrana. Tek tada je napravila wireframe s dugmetom na kartici prošle narudžbe.

Ukratko – 3.5 Prototipiranje korisničkog sučelja

• Prototip je jeftina rana verzija kojom se ideja provjerava s korisnicima.
• Nivoi vjernosti: papir, wireframe, mockup, interaktivni prototip, kod.
• Što je ideja neizvjesnija, to prototip treba biti jeftiniji.

3.6 Dizajn korisničkog iskustva

Korisničko iskustvo (UX) je sve što korisnik doživi: da li je brzo našao šta treba, da li je razumio šta se desilo, da li je imao osjećaj kontrole, da li bi preporučio aplikaciju prijatelju. Dobar UX se ne vidi; loš se vidi odmah.

Normanovi principi. Don Norman je u knjizi The Design of Everyday Things (prvo izdanje 1988) objasnio zašto ljudi guraju vrata koja se vuku. Vrata s ručkom „kažu” povuci, a ravna ploča „kaže” gurni. Ako dizajn kaže jedno, a vrata traže drugo, kriv je dizajn, a ne čovjek. Takva vrata se danas zovu Normanova vrata. Njegovi principi:

• Signal (signifier) – element pokazuje šta se s njim može: dugme izgleda kao dugme.
• Povratna informacija – svaka radnja dobija odgovor: „Narudžba poslana”, točkić dok čeka.
• Preslikavanje (mapping) – raspored kontrola odgovara posljedici: strelica gore pomjera gore.
• Ograničenja – nemoguće radnje su onemogućene: dugme „Naruči” je sivo dok je korpa prazna.

Nielsenove heuristike. Jakob Nielsen objavio je 1994. deset pravila po kojima se sučelje ocjenjuje i bez korisnika. Najvažnija za DeliveryApp:

3.6 Dizajn korisničkog iskustva

1. Vidljivost stanja sistema – kupac uvijek vidi gdje je narudžba (NOVA, U_PRIPREMI, NA_PUTU).
2. Podudarnost sa stvarnim svijetom – „Dostava 3,80 €”, a ne „DLV_FEE: 380”.
3. Kontrola i sloboda korisnika – „Poništi” postoji dok je to dozvoljeno (pravilo PP-6).
4. Dosljednost – dugme „Potvrdi” je uvijek na istom mjestu i iste boje.
5. Sprječavanje grešaka – adresa izvan zone se odbija prije plaćanja, ne poslije.
6. Prepoznavanje umjesto pamćenja – „Ponovi narudžbu” pokazuje šta je bilo u narudžbi.

Ostale četiri su: fleksibilnost (prečice za iskusne), estetski i minimalistički dizajn, pomoć pri prepoznavanju i ispravci grešaka, te pomoć i dokumentacija.

Pristupačnost. Proizvod koriste i ljudi koji slabije vide, ne razlikuju boje ili koriste čitač ekrana. Pravila WCAG traže npr. kontrast teksta najmanje 4,5 : 1 (NZ-4 u DeliveryApp) i opis svake slike. Promjena cijene u „Ponovi narudžbu” ne smije se označiti samo crvenom bojom; uz boju ide i riječ „promijenjeno”.

3.6 Dizajn korisničkog iskustva

Tamni obrasci. Suprotno dobrom UX-u su obrasci koji rade protiv korisnika: skrivena cijena dostave do posljednjeg koraka, unaprijed označena pretplata, dugme „Ne, hvala, ne volim uštedu”. Kratkoročno povećavaju prodaju, a dugoročno ruše povjerenje, i u Evropskoj uniji su sve češće zabranjeni propisima o zaštiti potrošača.

3.6 Dizajn korisničkog iskustva

Ukratko – 3.6 Dizajn korisničkog iskustva

• UX je cjelokupan doživljaj korisnika; dobar se ne primjećuje, loš se vidi odmah.
• Normanovi principi: signal, povratna informacija, preslikavanje, ograničenja.
• Nielsenovih deset heuristika služi za ocjenu sučelja bez korisnika.
• Pristupačnost i izbjegavanje tamnih obrazaca dio su profesionalnog dizajna.

3.7 Dokument specifikacije dizajna

Dizajn koji postoji samo u glavi jednog programera nije dizajn tima. Dokument specifikacije dizajna (SDD, software design description) zapisuje odluke tako da ih cijeli tim razumije isto, i da ih za godinu dana razumije i novi član. Standard IEEE 1016 opisuje šta takav dokument može sadržavati; u praksi je dovoljna kraća verzija.

Šablon koji koristi tim DeliveryApp (dvije do četiri strane po funkciji):

1. Svrha i obim – šta funkcija radi i šta ne radi. „Ponovi narudžbu pravi novu narudžbu sa istim stavkama, svježim cijenama i dostavom po trenutnoj tarifi grada. Ne mijenja adresu.”
2. Kontekst – ko koristi, na koje dijelove sistema utiče.
3. Struktura – klasni dijagram dijelova koji se dodaju ili mijenjaju.
4. Ponašanje – sekvencijalni dijagram glavnog toka i alternativnih tokova (jelo više ne postoji; cijena promijenjena; restoran zatvoren).
5. Sučelje – wireframe ekrana.
6. Podaci – koje se tabele ili polja dodaju.
7. Nefunkcionalni zahtjevi – npr. odgovor za najviše 2 s (NZ-1).
8. Odluke i alternative – šta smo razmatrali i zašto smo izabrali ovo (kratak zapis odluke; detaljno u poglavlju 7).
9. Otvorena pitanja – šta još nije odlučeno.

3.7 Dokument specifikacije dizajna

Ukratko – 3.7 Dokument specifikacije dizajna

• SDD zapisuje dizajn da bi ga tim razumio isto, danas i za godinu dana.
• Kratak šablon ima: svrhu, kontekst, strukturu, ponašanje, sučelje, podatke, NFR, odluke i otvorena pitanja.
• Dokument se piše prije koda i čuva u repozitoriju pored koda.

3.8 Alati za podršku dizajnu

Prednost dijagrama kao teksta (Mermaid, PlantUML) je ista kao prednost koda: vidi se šta se promijenilo između dvije verzije, i dijagram se pregleda zajedno s kodom. AI asistent može iz opisa riječima predložiti Mermaid dijagram za sekundu, ali tim mora provjeriti da li je dijagram iscrtan bez greške i da li odgovara stvarnim pravilima (npr. da nije izmislio vezu „Kupac ima Tarifu”).

Ukratko – 3.8 Alati za podršku dizajnu

• Za dijagrame koristimo Mermaid ili PlantUML (tekst u Gitu), a za prototipe Figmu ili papir.
• Dijagram kao tekst omogućava da se vidi šta se promijenilo i da se pregleda s kodom.
• AI prijedlog dijagrama mora se iscrtati i provjeriti prema pravilima domena.

Provjeri se

1. Koji nivo prototipa se prvo koristi za neizvjesnu ideju? Papirna skica, jer je najjeftinija.
2. Koju Nielsenovu heuristiku krši ekran koji piše „DLV_FEE: 380”? Podudarnost sa stvarnim svijetom.
3. Kada se piše dokument specifikacije dizajna? Prije programiranja, i mijenja se zajedno s dizajnom.

Odgovori: tipka R ili klik na zamućeno polje.

Dopunska praksa – wireframe i SDD za „Ponovi narudžbu”

Cilj je napraviti skicu ekrana i kratak dokument dizajna za jednu funkciju. Trajanje: jedan čas.

Korak 1 – Tri papirne skice (10 minuta)

Na papiru nacrtajte tri različita rasporeda ekrana „Moje narudžbe” s dugmetom „Ponovi”. Pokažite ih kolegi i zapišite šta je primijetio prvo.

Korak 2 – Wireframe

Najbolju skicu prenesite u Figmu (okvir veličine mobitela) ili u draw.io. Samo sive kutije i tekst: naslov, kartica narudžbe N-1001 (datum, restoran, stavke, ukupno), dugme „Ponovi”, ekran potvrde s iznosom 24,50 € i oznakom „promijenjeno” ako se cijena promijenila.

Korak 3 – Sekvencijalni dijagram

U repozitoriju deliveryapp-2 napravite docs/dizajn/ponovi-narudzbu.md i u njega upišite sekvencijalni dijagram iz odjeljka 3.2 (blok ``` `mermaid ``). Dodajte alternativni tok kad jelo više ne postoji (alt` blok).

Korak 4 – SDD

U isti fajl dopišite odjeljke iz šablona 3.7: svrha i obim, ponašanje (dijagram), sučelje (slika wireframea), NFR, jedna odluka s alternativom, otvorena pitanja.

Korak 5 – Heuristička ocjena

Razmijenite wireframe s kolegom. Svako ocijeni tuđi ekran po šest heuristika iz 3.6 i zapiše bar dva problema s prijedlogom ispravke.

Rezultat: docs/dizajn/ponovi-narudzbu.md s dijagramom, slikom wireframea i ocjenom kolege.

Vježba za studenta 1 – konceptualni model.

Vježba za studenta 1 – konceptualni model. – rješenje

Vježba za studenta 2 – SOLID.

Vježba za studenta 2 – SOLID. – rješenje

Vježba za studenta 3 – heuristike.

Vježba za studenta 3 – heuristike. – rješenje

Vježba za studenta 4 – prototip.

Vježba za studenta 4 – prototip. – rješenje

Sažetak u pet rečenica

1. Posjeta Applea Xeroxovom PARC-u 1979. podsjeća da ista tehnologija postaje proizvod tek kroz dizajn koji misli o korisniku.
2. Konceptualni model popisuje pojmove domena i veze, a u DeliveryApp 2.0 otkriva da je tarifa dostave podatak grada, a ne kod.
3. UML dijagram se bira prema pitanju (klasni, sekvencijalni, stanja, komponenti, razmještaja), a OO dizajn i principi SOLID čine da promjena na jednom mjestu ne izazove lavinu.
4. Prototip se pravi što jeftinije dok je ideja neizvjesna, a sučelje se ocjenjuje Normanovim principima, Nielsenovim heuristikama i pravilima pristupačnosti, bez tamnih obrazaca.
5. Dokument specifikacije dizajna piše se prije koda i čuva u repozitoriju, uz dijagrame kao tekst (Mermaid) koji se pregledaju zajedno s kodom.

Pitanja za ponavljanje

1. Šta se desilo u Xerox PARC-u 1979. i koja je pouka za dizajn proizvoda?
2. Šta je konceptualni model i po čemu se razlikuje od modela baze?
3. Šta znače višestrukosti 1, , 1.. i 0..1? Šta označava puni romb?
4. Koji UML dijagram koristite za koje pitanje? Navedite pet.
5. Objasnite apstrakciju, enkapsulaciju, nasljeđivanje i polimorfizam analogijom s automobilom.
6. Zašto su tarife tri grada jedna klasa s tri reda podataka, a ne tri klase?
7. Nabrojte i objasnite pet principa SOLID.
8. Kako princip inverzije zavisnosti pomaže kod rizika RZ-1 (adrese u Gradu B)?
9. Nabrojte nivoe vjernosti prototipa. Koje je pravilo za izbor?
10. Šta su Normanova vrata? Nabrojte četiri Normanova principa.
11. Navedite šest Nielsenovih heuristika s primjerom iz DeliveryApp.
12. Šta sadrži dokument specifikacije dizajna i kada se piše?