I’m at work and we are in the middle of a discussion regarding SAD (Software Architecture Document) and witch diagrams that should be included in the document?

We are talking about:
1. Use Case diagram
2. Object diagram
3. Sequence diagram
4. Class diagram
5. Activity diagram
6. State diagram
7. Package diagram
8. Component diagram
9. Deployment diagram

My proposal is to not involve to many diagram that describes nearly the same ting as some other diagram, for example Package diagram and Component diagram. There for I'm excluding Object diagram, State diagram, Package diagram.
There are of course some depending like, what kind of program you are building, but we are talking about in general.
What's your opinion?
Witch diagram do you recommend that should be included in a architecture document?

Ni kan svara på svenska...

Regards Z

måste leka språk polis "Witch diagrams" == häx diagram :)

jag saknar ett översikts bild , lager diagram (layerd diagram), brukar man ha med i ett kapitel om den logiska vyn.

> måste leka språk polis "Witch diagrams" == häx diagram :)

språk polis? Kasta sten i glas hus? ;)

Apropå det, vad finns det för glashus som inte är växthus eller "drivhus"?
Ordspråket kunde vara "kasta inte sten i växthus" istället... ;)

Tack för hjälpen... NOT!

Man behöver inte ha med alla, utan man tar de diagram som krävs för att förmedla hur designen skall vara. Det får inte finnas några luckor någonstans.

>>Tack för hjälpen... NOT!

inga problem :)

Pensionärskupoler borde kunna räknas till glashus, likaså vissa lusthus...

Lite onödigt trollande i denna tråd... Skärpning tack! :) :P

-Moderatorn har talat!!!

Som inbiten scrum-älskare skulle jag nog säga kasta alla de där dokumenten ;-)
Gör ett kort dokument om arkitektens designidé. Dvs på modulnivå... behvöer inte ha med sekvens diagram, klassdiagram m.m. Aldrig någon som kommer orka uppdatera dem ändå.

Om 1-2 månader kommer det vara så mkt dokument att ingen ens kommer orka göra alla dessa diagram och man sitter där med en hög papper på saker som man inte ens vet om de talar sanning eller ljuger då all utveckling mer eller mindre faktiskt är agila.

Samma gäller eviga nerfläckandet och snuskandet med kommentarer i kod... usch... Dokumentera mindre, dokumentera bara det viktigaste, gör klasser, metoderm variabler, och projekt självbeskrivande med bra och tydliga namn, Dela även in systemet i modulmappar om vissa projekt/lager blir lite stora.

Använd gärna ///Summery comment på publika metoder, men med rät kort förklaring, se alltid till så dessa kommentarer oxå är uppdaterade, kan man inte håller dem uppdaterade så strunta i dem. oftast behövs de inte så vida man inte bygger ett ramverk som andra skall använda...

Gör ett 15-30 sifor dokument om systemets design. Kort beskrivning vad det är för system. Ev indelning av lager och kort vad de är till för. Resten kan man sedan läsa i koden där man ändå vill in o greja...
Gör tydliga Nunit tester till allt (dessa fungerar även som dokumentering)

Kör gäran städnig kodreview på koden så alla förstår den, skapar det frågetecken från teamet beror det oftast på att man skrivit kass kod. Kör man med SCRUM som metodik så har man ju dagliga möten vilket hjälper utvecklarna att hänga med på vad de andra gör för saker så alla får kunskap av systemet.

mvh Johan

"Samma gäller eviga nerfläckandet och snuskandet med kommentarer i kod... usch... Dokumentera mindre, dokumentera bara det viktigaste, gör klasser, metoderm variabler, och projekt självbeskrivande med bra och tydliga namn"

Kan bara instämma med Johan samt varmt rekommendera böckerna Clean Code och/eller Code Complete! Kommentarer i kod == en ursäkt för att man inte skrivit tydlig kod!

>>Kör gäran städnig kodreview på koden så alla förstår den, skapar det frågetecken från teamet beror det oftast på att man skrivit kass kod.

Vad hjälper det om 5-10år när de inhyrda resurerna är och skapar nya system och inte finns tillgängliga?

Om man har tydlig och välskriven kod + tydliga och heltäckande enhetstest så har man i alla fall en chans att applikationen fortfarande kan förvaltas och nya "förvaltare" kan skolas in. Saknar man det så innebär 5-10 år oftast att det är dags för den klassiska "vi måste skriva om allt från scratch för ingen törs ändra i koden längre"

Om man har inhyrda resurser som utvecklar åt en så bör man nog vara särskillt noga med att dom lämnar tydlig och vältestad kod efter sig för annars riskerar man att ha dyrt investerat i en snabbt "ruttnade" kodmassa.

>>Om man har inhyrda resurser som utvecklar åt en så bör man nog vara särskillt noga med att dom lämnar tydlig och vältestad kod efter sig för annars riskerar man att ha dyrt investerat i en snabbt "ruttnade" kodmassa.

så du menar på fullt allvar att "bra kod" ersätter dokumentation av ett system som är tänkt att leva länge? Låter ju väldigt intressant måste få citera dig näste gång en kund vill ha dokumentation.

Helt ok att citera :)

Visst behövs det viss annan dokumentation (driftdokumentation , användarmanualer m.m). Men för teamet som skall förvalta så hävdar jag att det räcker med:

1. En översiktlig skiss av systemet
2. Tydlig kod
3. Tydliga enhetstest som är "gröna" samt täcker hela kodmassan (detta anser jag vara en förutsättning för att man överhuvudtaget skall kunna göra förändringar i koden utan att riskera en massa regressionsbuggar).

Personligen så hatar jag att dokumentera :)

Jag vill kasta mycket av de dokument som du tar upp, dock behålla några av dem.
Som de flesta av oss vet, så är det ett j-vla jobb att hålla dessa dokument "Up to date". Därav anser jag att det är nästan bättre att strunta i dem.

Försök att då istället använda en väldigt tydlig kod, låt den beskriva sig själv. Använd gärna kommentarer i koden, dock endast där det är otydligt vad som sker, om inte denna kod kan skrivas om.

Men om jag skall yttra mig om vad jag vill behålla för dokument så är det bla:

- Use Case diagram (tydligt vilka roller systemet behandlar samt vad dessa kan göra för något) tycker om dessa.. :)

Jag tror att allt handlar om typen av projekt.

Ett stort projekt för t.ex. ett sjukhus där det är ett team som utvecklar programvaran och ett som skall underhålla det.

Eller när det handlar om projekt där 20 eller fler involveras så tror jag att man måste ha någon slags SAD som beskriver hur de olika projektgrupperna skall integrera varandras kod. T.ex. att man specifierar hur varje komponent skall integrera med andra komponenter som andra projektgrupper utvecklar.

Att enbart köra agile utan att se på hur projektet ser ut tycker jag låter dumt.

Sedan tycker jag agile är ett extremt trevligt sätt att arbeta på, krävs dock att man underhåller sin kod dvs reviews/refactoring.

Så sant.

Givetvis måste man se till projektets storlek för att ge riktigt bra svar på vilka diagram som bör finnas i SAD. Agile metoder blir mer och mer populära, men de kanske inte passar in överallt.

Andreas:
>>Vad hjälper det om 5-10år när de inhyrda resurserna är och skapar nya system och inte finns tillgängliga?
Det är just det. Välskriven kod, struktur med enkla design dokument hjälper till mer än vad många vågar tro.
Ex tänk själv, när du kommer till ett nytt projekt vad gör du då? Hur många ggr har de dokument du ev fått i näven verkligen vart up to date? Hur mkt tid har man inte kastat på att uppdatera dokument som kanske ändå bara 10% av teamet kommer orka läsa?
Kod dock, det läser man hela tiden. Att leta i kass kod är nog det värsta som finns. Debugga i timmar för att fatta vad folk gjort... O deras ursäkt är alltid - har du inte läst våra dokument? Det är inte ens så det skall gå till. Kod skall inte vara ??? utan kod skall vara en tänd lampa hela tiden. Varje frågetecken man får när man läser kod är rent av 100% tecken på kass kod. Förstår man den inte är den kass skriven, det bara är så... Och inget man kan argumentera sig ur.

Om en kund säger vi vill ha dokument, fråga då kunden varför? och vem det är som skall läsa den?
De kunde rjag jobbat med vill oftast ha design dokument, de vill veta lite hur man tänkt arkitekturen, vilka moduler finns i systemet. Koden läser sen utvecklarna.

Fört att få bättre insyn på vad bra kod är så föredrar jag boken Refactoring av Martin Fowler, Code Complete från MS Press och Clean Code som nyligen kom ut. 3 böcker som kommer ändra synsättet på många plan.

Tänk på att det faktiskt är så att måste nått förklaras så är det otydligt. Det bara är så hur mkt man än vill argumentera emot det. Är nått otydligt och måste förklaras så är det rätt kass gjort.
Utvecklare läser kod inte uppsatser... Om 5-10 år är man glad om man kommer till kod som är lättläst och tydlig och självbeskrivande... men du är inte glad om 5-10 år och måste läsa en sjö dokument som ingen ändå uppdaterar. För så är det 99% av alla fall så ljuger dokumentationen, ingen kommer orka göra om 300 sekvensdiagram bara för man väljer att flytta om ett flöde då ett nytt krav kom till. Ingen kommer orka skriva om 50 sidor pga det nya flöden. Ingen kommer orka ändra alla klassdiagram för att nya klasser kom till. Men man kommer alltid orka läsa koden och vill gärna att ändringar i koden skall vara så enkla som möjligt med minsta lögn...

Lycka till säger jag bara :)

Mvh Johan

Niclas:

Storleken har ingen betydelse :-)
Se SCRUM google har kört med det. utan problem... MS har kört det i vissa projekt. m.m.
SCRUM är just en agil metodik och en av de få som faktiskt har dokumenterade bevis på att fungera i både stora och små projekt.

Att integrera olika moduler är lite av vad just ett design dokument kan hjälpa en med. Sen är det klart att man skall ha någon slags dokumentation men det beror på för vem man skriver dem. Gör man en modul som ett annat systerm skall använda vill man ju gärna ha ett design dokument om modulen. Det kan täcka med 2-3 sidor som bara tala rom vad den gör, vilka kontrakt som finns och hur man skall tolk akontraktet. Det behövs varken sekvens eller klassdiagram för att hjälpa någon att använda en redan tillvärkad modul. Sjukhus som bilverkstad spelar ingen roll.

Kolla bara SOA där det typ är fokus på design dokument och mindre fokus på dess innre kod. Dvs det är inte tjänsteanvändarnas uppgift att veta hur insidan av en tjänst ser ut... Och insidan är det ändå bara kodare som pillar på så för dem är det viktigt med bra kod och ett väldeffinerat kontrakt och med ex enhetstestning, Design by contract och defensive programming så har man troligen redan satt upp krav o regler vad APIerna får och inte får göra m.m.

Jag ser just nu egentligen bara ett skäl till massa dokument och det är om man skall outsource sakerna men inte vill att de som kodar skall vara med och bestämma flöden, klasser m.m. Men sådan utveckling har aldrig givit bra resultat vad jag vet.

Mvh Johan

>så du menar på fullt allvar att "bra kod" ersätter dokumentation av ett system som är tänkt att leva länge? Låter ju väldigt intressant måste få citera dig näste gång en kund vill ha dokumentation.

Jag kan bara säga... JA... Bra kod ersätter dokumentation på teknisk nivå...

Det är mycket möjligt att du har rätt, jag är ingen expert på området.

Självklart så skall man fortfarande ha fokus på koden även om man har dokumentation.
Om inte annat tror jag dokument/whiteboard kan vara bra att rita t.ex. vilka states ett objekt/komponent skall ha innan man sätter sig ner och skriver kod. (Men det har ju inte med den dokumentation vi diskuterar om).

>Det kan täcka med 2-3 sidor som bara tala rom vad den gör, vilka kontrakt som finns och hur man skall >tolk akontraktet. Det behövs varken sekvens eller klassdiagram för att hjälpa någon att använda en >redan tillvärkad modul. Sjukhus som bilverkstad spelar ingen roll.

Är det inte kontrakt och generell arkitektur som är det viktiga i en SAD? (så just en SAD kanske inte skadar, även om den slängs efter man har börjat :)).

Johan:

>> men du är inte glad om 5-10 år och måste läsa en sjö dokument som ingen ändå uppdaterar. För så är det 99% av alla fall så ljuger dokumentationen, ingen kommer orka göra om 300 sekvensdiagram bara för man väljer att flytta om ett flöde då ett nytt krav kom till.

Jag har inte sagt något om hur omfattande en systemdokumentation ska/bör vara det är du som tror att det ska vara diagram och beskrivningar av koden. Det är enbart slöseri med tid att göra en sådan dokumentation på kodnivå, där håller jag med dig. Men du påstår att din fina kod dokumenterar systemet, där faller dina argument åtminstånde enligt hur jag ser på systemutveckling och förvaltning av system. Ett system måste ha en förklaring / dokumentation som inte är kod.

Andreas:
jag utgår från de punkter som skrevs i post nr 1
We are talking about:
1. Use Case diagram
2. Object diagram
3. Sequence diagram
4. Class diagram
5. Activity diagram
6. State diagram
7. Package diagram
8. Component diagram
9. Deployment diagram

Där av kommentarer om diagram och sekvensdiagram m.m.

>Jag har inte sagt något om hur omfattande en systemdokumentation ska/bör vara det är du som tror att det ska vara diagram och beskrivningar av koden. Det är enbart slöseri med tid att göra en sådan dokumentation på kodnivå, där håller jag med dig. Men du påstår att din fina kod dokumenterar systemet, där faller dina argument åtminstånde enligt hur jag ser på systemutveckling och förvaltning av system. Ett system måste ha en förklaring / dokumentation som inte är >kod.

Asså varför måste man det? PS... Syftar inte på att man inte skall ha Installations dokument... Jag syftar på just om 5-10 år senare. varför måste det finnas dokumnent då? När svaren finns i koden och i ett enkelt övergripande designdokument?