Allmänt om programmeringsprojektet i TDDI02


VIKTIG NOT!
Dokumentet i den här versionen avser kursen före år 2007, när den hette TDDI38 och dels gick över två perioder, dels hade en poäng till. TDDI02 är en lite reducerad variant, och därför gäller inte allting här. När det blir tid över kommer texten att anpassas.

Mycket av det här dokumentet är hämtat från I-arnas (och D-arnas) projektkurser. Ni har lite större frihet i ert projekt (eftersom ni förväntas kunna mer!), och därför kan det hända att en del saker är lite för noggrant specificerade. Se det som ett hjälpdokument, som kompletterar det som står i kursinformationen och sägs på föreläsningarna och av handledarna!

Dokumentet består av:
- Allmänt om uppgiften, Mål, Förberedelser och Examination (denna del)
- Kortfattad handledning i hur man genomför ett projekt av denna storlek, följt av en lista med krav på lösningarna.

Mål

Målet med uppgiften är att studenten, genom implementering av ett lite större program, dels ska förvärva programmeringsvana, dels ska få insikt i och kunskap om de arbetsuppgifter och problem ett programmeringsprojekt innebär. Till denna uppgift beräknas 50-100 timmar för inskrivning och testning av program. Förberedelser (planering, informationssökning, specifikationer) och dokumentation beräknas ta ca 50-70 timmar. Som ni snabbt inser kommer det att behövas en hel del hemarbetstid. Planera denna i början av kursen! Tiderna gäller per person i gruppen.

Förberedelser

Eftersom laborationstiden (antal timmar bokade i Pul) är relativt begränsad i förhållande till projekttiden, så är det extra viktigt att ni förbereder er ordentligt inför varje bokat laborationstillfälle. Innan varje laboration bör ni alltså ha skissat upp den kod ni tänker skriva in, antingen som färdigskriven kod, pseudokod, någon form av schema eller liknande. Men givetvis måste ni också utnyttja andra tider!

Examination

Examination sker i tre steg: Närmare beskrivning av de olika delarna och dokumenten finns på efterföljande sidor. Efter beskrivningarna finns en kortfattad sammanfattning över vad som ska ingå i de olika dokumenten.

Handledning till projektuppgifterna

Uppgiftsbeskrivningarna som följer efter denna handledning är formulerade som scenarion, där en presumtiv kund vill ha en datoriserad lösning till något problem. Kunden och/eller någon till kunden närstående person (som i en del fall har tveksamma kunskaper om vad som kan göras med datorer och hur svårt det blir) har författat en önskelista över vad de vill att systemet ska klara av. Denna något luddiga önskelista är troligen inte fullständig, och/eller kan innehålla i vissa delar irrelevanta funderingar. Uppgifterna är medvetet utformade så för att spegla de problem en systemutvecklare ofta hamnar i.

Börja därför med att läsa igenom denna handledning (hela handledningen).

Därefter läser ni uppgifterna, och väljer ut den av dem som ni vill göra (ni får även hitta på en egen uppgift, men denna ska då godkännas av handledaren. Svårighetsgraden kan ofta vara svår att förutse.). När ni valt uppgift ska ni göra följande (utförligare beskrivning på följande sidor och en sammanfattning därefter):

När ni fått tidsplanen och kravspecen godkända, ska ni: När designspecen är godkänd ska ni: Till slut ska ni: Detta kan verka mycket, men det visar sig att om man lägger ner lite arbete på kravspecifikationen och designspecifikationen så kan de dokumenten med relativt små tillägg och ändringar återanvändas i användarhandledningen och programdokumentationen. Flera av dokumenten ovan blir sällan större än ett par A4-sidor i detta projekt. Det är viktigt att dokumenten är välskrivna och att de vänder sig till rätt målgrupp.

Tidsplan

Bestäm en tidsplan för projektet, d.v.s. avsätt tid i ert schema till de olika momenten i projektet. En ungefärlig tidsåtgång kan vara: Ange vad som hör till de olika faserna i projektet, och välj också ut några relevanta milstolpar!

Tänk på att alla deadlines som finns angivna i kursinformationen är inklusive all reservtid, så ni måste planera att vara klara i god tid! Se till att ni siktar på att vara klara minst en vecka före sista inlämningsdatum, så att ni har lite marginal mot slutet. Lägg största arbetsinsatsen i början!

Det ska klart framgå när (vilka dagar och kanske också vilka timmar under dagen) de olika delarna nämnda ovan är tänkta att utföras. Det ska dessutom framgå när olika dokument ska lämnas in.

Observera att detta är till för er och för att ni ska boka in både projektet i denna kurs och även de andra kursernas olika delar. Det som många inte tänker på är att det också ska finnas inbokad ledig tid. Man arbetar bättre efter en god natts sömn eller en ledig helg. Vi vill dock endast ha in den del av er planering som avser denna kurs!

Under projektets gång ska ni anteckna hur mycket tid ni verkligen arbetar de olika dagarna, så att ni senare kan jämföra med vad ni planerat. Lägg gärna till en extra kolumn för detta ändamål i er tidsplan. En liten projektdagbok kan alltså vara av värde!

Specificera programmet (eller systemet): Kravspecifikationen

I ett riktigt projekt delar man ibland upp kravspecifikationen i två delar (en mot beställaren, den externa specifikationen, och en internt på företaget, den interna specifikationen), men i detta projekt slår vi ihop dessa.

Vad ska då ingå i detta dokument?

Tänk på att detta dokument är det som motsvarar ett avtal mellan er och beställaren. Det ni lovar här måste fungera när tiden är inne för leverans av systemet. Det finns naturligtvis möjligheter att ändra på dessa krav under kursens gång, men detta måste ske i samförstånd med er handledare. Även handledaren kan ändra på era krav under kursens gång om det verkar vara väldigt snett med belastningen, men detta är inte det normala fallet. Det är också gentemot kravspecen som det färdiga systemet kommer att testas!

Dessa krav bildar ett embryo till den användarhandledning ni så småningom ska skriva. Har ni gjort den bra och fullständig och sedan verkligen implementerar systemet så att det utåt sett fungerar exakt som kravspecifikationen anger - ja, då är er användarhandledning nästan klar!

Vilka funktioner (arbetsuppgifter) och krav ska programmet klara av? I det minimala fallet blir denna lista samma som de kommandon som nämns ovan, men oftast måste ett program klara mera än vad det verkar när man ger ett kommando. T.ex. krävs ofta kontroller av att inmatade data är riktiga, det kan finnas krav på att programmet aldrig får ha längre svarstider än ett visst antal sekunder eller att det ska kunna garantera att den information som bearbetas i programmet inte går förlorad om datorn går ner. Andra vanliga krav är att det ska gå att köra programmet på si eller så små datorer (begränsningar i minne och exekveringsprestanda).

Ett sätt att angripa problemet är att skriva en bra specifikation:

Denna specifikation blir alltså en lista av krav eller löften om vad programmet ska klara, och kallas ofta för kravspecifikation.

Innan ni så småningom börjar koda, måste denna lista godkännas av er handledare. Det är detsamma som att ni lovar att implementera det som står i listan och uppfylla de krav som nämns där. I en verklig situation är kravspecifikationen ett kontrakt eller avtal mellan systemutvecklare och kund som reglerar vad som ska göras, hur det ska göras och till vilken kostnad.

Systemdesign: Designspecifikationen

Här ska du beskriva hur du tänkt implementera programmet och hur programmet "exakt" ska se ut gentemot användaren. Beskrivningen sker i två delar, val av datastruktur och val av programstruktur. Detta innebär inte att du när du designar systemet har tagit den ena delen före den andra. Själva designarbetet är ju en kombination av att dela upp det stora problemet i mindre och att välja datastrukturer som fungerar ihop med detta.

Under arbetets gång har du troligen fattat beslut om vilket (vilka) programspråk du vill använda för din implementation. I somliga fall kan vissa detaljer i designarbetet påverkas av detta val. Men beroendet bör vara minimalt.

Ni får självklart använda olika existerande kodbibliotek, till exempel för grafiska användargränssnitt.

Att välja datastrukturer

Här bestämmer man hur data ska lagras i programmet. I uppgiften står mer eller mindre preciserade idéer om hur man kan lagra de data som programmet behöver. Granska dessa förslag kritiskt och tänk efter om de duger för den funktion du beskrivit i kravspecifikationen. Är det eventuella förslaget på strukturen krångligare än nödvändigt, gör en enklare version. Går det inte att klara alla kraven och funktionerna, modifiera så att det fungerar.

När principen för strukturen är klar ska du bestämma vad alla komponenterna ska heta (t.ex. vilka typer av poster det ska vara, vad fälten ska heta och vad det ska vara i dem) och hur t.ex. en pekarstruktur av poster sitter ihop. Rita en bild (med boxar, pilar, namn och förklaringar) över hur strukturen ska se ut. Här ska givetvis också en bild över hur data lagras på fil finnas med (se nedan).

I de fall data lagras på fil används ofta en helt annan struktur än inne i programmet. Hur den strukturen ser ut och vilka operationer som läser in (och eventuellt konverterar) eller skriver ut data ska naturligtvis också beskrivas här.

Beskriv även de eventuella globala variabler som programmet behöver. Men undvik helst globala variabler, med de problem som då uppstår med biverkningar ("sidoeffekter")! Använd i stället lokala variabler och funktionsparametrar, eller kapsla in variablerna med åtkomstfunktioner. Använd naturligtvis klasser om ni skriver i språk som stödjer det.

Grundprincipen i val av datastrukturer är att man vill undvika redundans (att samma information lagras på flera ställen) och man vill underlätta för de beräkningar/arbete som programmet ska utföra. Dessutom vill man givetvis inte dimensionera datafält större än nödvändigt.

Beskriv sedan vilka operationer som ska kunna utföras på datastrukturen. Sätt namn på operationerna (modulerna som utför operationerna) och ange vad de behöver för argument och vad de returnerar. Du kan t ex använda följande mall då du beskriver dina moduler: 

	Modulnamn:   SkapaPerson
        Vad den gör: Skapar en personpost och returnerar en pekare till posten.
        Indata:      Namn            en sträng (högst 40 tecken)
                     Personnummer    en sträng (11 tecken)
        Utdata:      - - -
        Kända fel:   - - -
Den sista punkten ("Kända fel") behöver ni bara ha med i systemdokumentationen, men vi tar upp den nu iallafall.

Detta arbete är det som tar längst tid i förberedelserna, men är det som underlättar mest för programmeringsarbetet. Man bör skapa sig ett antal moduler, t ex som hanterar datastrukturen och sedan i övriga delar av programmet använda dessa moduler istället för att arbeta med uttryck som "person->next->name". Detta kallas dataabstraktion och underlättar t.ex. om ni vill ändra i er datastruktur. Dataabstraktion kan även användas för att lätt kunna byta ut algoritmer i programmet.

Att välja programstruktur

Här ska du beskriva ungefär hur du kommer att strukturera ditt program, d.v.s. vilka `moduler' som finns, vilka uppgifter de har och hur de samarbetar, d.v.s. anropar varandra.

Med en modul kan man mena olika saker, beroende på efter vilka principer man delar upp problemet. Ett sätt är att dela upp efter funktion (d.v.s. efter vad de gör - alla funktioner som har med inläsning av data från fil hamnar i en modul, o.s.v.). Ett annat sätt är att bara dela upp problemet i mindre delar utan att tänka i begreppet C-funktioner, eller motsvarande.

Båda dessa "metoder" är varianter av programutvecklingsmetoden `top-down'. Det "träd" du får fram ska i sig beskriva hela programmet. Den förstnämnda varianten (att tänka i funktioner) kräver mer av den som designar eftersom det redan från början måste tänkas på vad som ska "klumpas ihop" till en (C-)funktion. Den sistnämnda varianten leder till ett lite större "modulträd", men har den fördelen att man ser vad som händer var man än tittar i detta träd. Rita gärna upp modulträdet!

Du kan läsa mer om designmetoder i boken Software Engineering! Troligen kommer du nån gång att använda stegvis förfining, som finns beskriven i kapitel 7. För den mer övergripande designen kan en objektorienterad design vara bäst, kanske oberoende av ditt språkval!

Sätt er inte och gör specifika moduler för varje ny typ av (komplex) bearbetning utan använd de som redan är definierade, d.v.s. om du redan har en modul som klarar av att utföra uppgift A så behöver du ju inte göra en specifik modul som klarar av uppgiften B, där A igår som en deluppgift, utan bara de delar som inte finns i A och sedan anropa A från B.

Arbeta uppifrån och ner i trädet. Först huvudmodulen (gör en modulbeskrivning). När detta är klart kan ni plocka fram de underliggande modulerna från huvudmodulen. Tag en av modulerna och se den som en ny huvudmodul. Fortsätt tills det att du inte kan dela upp problemet i mindre delproblem.

Implementering. Programdokumentationen.

Nu ska ni skriva kod, i ett relevant programspråk, som gör det ni beskrivit i designspecifikationen tidigare. Samtidigt som ni gör det ska koden dokumenteras, d.v.s. vänta inte med dokumentationen till sist! Om ni verkligen följer er designspecifikation behöver ni bara utöka texten med de detaljer som tillkommer, t.ex. om en modul är en funktion eller flera funktioner samlade i en källkodsfil, vilka parametrar funktionen tar och vad den returnerar, och hur. Sedan är dokumenteringen klar för den modulen.

När ni ska skriva programkoden kan ett tips vara att ni kopierar den modulbeskrivning ni gjort till en ny fil som heter t.ex. `projekt.c' (det filnamn som ni tänker använda till ert program, och med C som språkexempel), detta ger en stor vinst för dem som skrivit sin dokumentation på samma dator (och i samma editor) som de tänker skriva programkoden. Det är lämpligt att sätta alla modulbeskrivningarna i separata kommentarer (detta gäller förstås bara i själva koden) och sedan skriva koden "kring" dessa. Om det blir några ändringar i modulbeskrivningarna under programmeringen är det lätt att plocka ut dessa till programdokumentationen senare.

Tänk på kodningsstilen!

Skriv inte för mycket! Som riktmärke i dessa projekt: de tre till fem största underprogrammen kan ni ge max en halv A4 dokumentation var, övriga mindre. Ser det ut att bli mer, så bör ni diskutera det med er handledare. Dessutom ska inte en funktion/subrutin bestå av fler rader än ca en sida. Detta för att man snabbt ska förstå modulens funktion och dessutom att man ska se hela modulen på en gång.

Tänk på vilken typ av läsare ni skriver till! Läsaren är en annan programmeringskunnig person, så ni kan skriva kortfattat och använda vanlig programmerarterminologi utan att förklara orden.

Programdokumentationen består alltså av två delar: De förklaringar ni skrivit och själva koden. Koden (ofta en tjock bunt papper, kan med fördel skrivas ut tvåspaltigt) lägger ni som en bilaga i slutet av systemdokumentationen. Det ska finnas modulbeskrivningar i koden också!

OBS! Det är inte samma modulbeskrivningstyp i programdokumentet som i designspecifikationen. Här ska varje modul vara minst en funktion, och på det sättet försvinner en hel del av det designmässiga modulträdet. Det är därför mycket viktigt med bra modulbeskrivningar i detta dokument.

Hur kör man programmet? Användarhandledningen

Här ska ni skriva ett dokument för en helt annan kategori läsare än tidigare. Nu är det den datorokunnige användaren som ska läsa. Dom kan inte förväntas förstå att man alltid måste trycka på [RETURN] efter varje inmatning, att teckensekvensen `[RETURN]' i ert dokument betyder `knappen på tangentbordet med ordet RETURN på', o.s.v.

Följande är ett exempel på innehåll i en användarhandledning:

Hur det gick: Efterstudien

Det är här ni ska presentera en `utvärdering' av ert arbete. I korthet går det ut på att ni ska jämföra er ursprungliga tidsplan, kravspecifikation och designspecifikation med hur mycket tid ni verkligen arbetade och vad ni implementerade. Blev det några skillnader så kan man försöka förklara varför inte planeringen höll. Kanske ni har lärt er något speciellt. Skriv ner vad isåfall. Detta dokument ska vara en del av din egen 'erfarenhetsbank'.

Om det är något speciellt ni tycker om projektkursen kan ni ta upp även det under den här punkten. Andra synpunkter angående handledning, laborationer eller handledaren kan också placeras här. Den ersätter alltså också den vanliga kursvärderingen, som ni brukar få efter kurserna. Men blanda inte ihop de två utvärderingarna - ditt projektgenomförande och 'kursvärderingen'.

Att lämna in: Systemdokumentation

Systemdokumentationen innehåller: Så, nu vet ni vad ni ska göra! Mycket nöje!

Krav på lösningarna

Förutom vad som sagts ovan och vad som meddelats av kursledningen och er handledare gäller följande:

TIPS, om du inte kommer ihåg

Använd lämpliga flaggor till kompilatorn, så att den hittar så många fel som möjligt. Till cc kan man ge flaggorna "-X c -v -g", och till gcc kan ni ge flaggorna "-Wall -Wtraditional -ansi -pedantic -g". Utnyttja också avlusningsverktyg, t. ex. debuggern debugger. Programmet indent formatterar C-kod snyggt, något som även kommandor M-X indent-region i Emacs kan användas till.

Kort sammanfattning av vad som kan finnas i de olika dokumenten

Thomas Padron-McCarthy, 27 augusti 1999.
Med tack till Torbjörn Jonsson, Peter Loborg m fl.
Lite bearbetat av Olle Willén, 2005