KRAV TIL RAPPORTEN Eksamensprojektet i Web-programmering og Datakommunikation skal afleveres som en rapport. Rapporten skal afleveres, i 2 eksemplarer (kopier). Endvidere skal være angivet URL, for emner med implementering af web-applikationer evt. med angivelse af login og password, hvis nødvendigt. Hvert eksemplar skal være forsynet med den obligatoriske forside, som I henter på CampusNet. Rapporten må af praktiske grunde ikke afleveres i et ringbind, men gerne i en blød plastikmappe, implementeringer af websider/-applikationer skal endvidere suppleres med en CD indeholdende kildekode (html scripts mv.). Det enkelte eksemplar, skal være forsynet med en indholdsfortegnelse, så man kan finde rundt i rapporten via denne. Alle sider skal være fortløbende nummereret. Hvis jeres besvarelse indeholder elementer, der er kopieret fra andre kilder, skal der udtrykkeligt henvises til de pågældende kilder. Hvis det omvendt konstateres, at besvarelsen helt eller delvist er identisk med andre kilder (uden at dette er angivet), vil dette blive betragtet som eksamenssnyd med de deraf følgende konsekvenser. Rapporten bør maksimalt fylde 10 sider pr. gruppemedlem (programmets kildetekst samt øvrige bilag ikke medregnet). Der gøres opmærksom på, at bilag ikke nødvendigvis gennemlæses i sin helhed af eksaminator og censor. Derfor er det en god idé at lave henvisninger fra rapporten til bilag, hvis man vil henlede censors opmærksomhed på en genistreg i gruppens kode. Eksempel på en indholdsfortegnelse: 1. Indledning 2. Analyse 3. Design 4. Implementering 5. Afprøvning 6. Vedligeholdelsesvejledning 7. Konkusion 8. Bilag: Screendumps og kildekode Rapporter af mere teoretisk karakter vil ofte have 3. Syntese i stedet for (Design Implementering afprøvning vedligeholdelsesvejledning) i dette afsnit kan så forekomme test af f.eks. forskellige browsere husk at vedlægge dokumentation fx skærmdumps. Side: 1/6
I det følgende ses nærmere på hvad rapportens dele indeholder. 1. Indledning Normalt beskriver man her kort, hvad indholdet er, hvem der har lavet rapporten og målgruppen. Målgruppe er i dette tilfælde den virtuelle opgavestiller (DTU), ellers primært eksaminator og censor. Evt. kan der optræde en sekundær målgruppe, det kunne i dette tilfælde være andre studerende, som på et senere tidspunkt kunne tænke sig at se enten indhold, eller hvordan man opbygger en rapport på DTU i forbindelse med et eksamensprojekt. Det skal af enten indholdsfortegnelsen eller indledningen klart fremgå, hvem der har lavet hvad. Der må kun stå et navn på hvert navngivet afsnit eller punkt. 2. Analyse Formålet med at foretage en analyse f.eks. af problemet Lav et Web-site til registrering af Projekter, skulle gerne munde ud i en kravspecifikation, som kan danne grundlag for design og implementering. I dette afsnit skal I dokumentere de væsentlige løsningsovervejelser I har gjort jer, og de væsentlige valg I har truffet i forbindelse med udviklingen af systemet. Løsningsovervejelserne skulle gerne munde ud i forskellige forslag til, hvordan man når det samme mål. Det er her i skal foretage et valg mellem flere forskellige løsningsmetoder og det er vigtigt at I begrunder jeres valg. Hvis I vurderer, at der i beskrivelsen af problemstillingen er manglende eller modstridende oplysninger, bør I definere og dokumentere nogle forudsætninger som opgaven så løses ud fra. - Dette vil ofte være tilfældet i en tænkt problemstilling som i denne opgave, hvor I jo kun har beskrivelsen at holde jer til - men ingen brugere at interviewe. - Hvis I vurderer, at det er nødvendigt at foretage visse afgrænsninger af opgaven, for at den realistisk kan løses, bør disse begrundes og dokumenteres. Hvis I ender med 3 forskellige metoder (algoritmer) til at løse en konkret opgave så beskrive disse 3 metoder foretag derefter et valg af den metode, I vil anvende og begrund valget, f.eks.: Vi valgte metode A, idet den anvender mindre båndbredde, da en del af funktionaliteten ligger på klientsiden. Husk at fravalg af en alternativ metode også er et valg, som skal begrundes. I analysefasen, fastlægger man blandt andet også hvilke oplysninger data, vil arbejde med og gemme. Husk, at alt bliver beskrevet abstrakt, I skal altså ikke i analysedelen begynder at inddrage xhtml, php eller SQL her, men blot sige vi ønsker at gemme oplysninger om personer, deres navne og deres whatever, men ikke noget om $navn eller VARCHAR(10) her. Dokumentation fra denne fase: Kravspecifikationen er udbyttet fra analysefasen. Kravspecifikationen indeholder oplysninger om den ønskede funktionalitet (stadig kun på et abstrakt plan) og hvilke oplysninger der skal kunne fremfindes i systemet. I et projekt af mere teoretisk karakter, er analysen en opstilling af undersøgelser foretaget enten som empiri eller vha. teoretiske fakta. Side: 2/6
3. design I designfasen, skal I ud fra kravspecifikationen, designe systemarkitekturen. Det er jo et krav, at I anvender 3-lagsmodellen. (se noten kom godt i gang.) Den består øverste af brugergrænsefladen, i midten er funktionslaget og nederst datalaget. Dvs. øverste lag vil i implementeringsfasten blive et mix af xhtml, css og (php)script-genererede skærmbilleder. Funktionslaget er lidt mere komplekst det vil være et mix af klientscript serverscript (e.g. javascript php-script ) og SQL som jo kompliceres yderligere af at være spredt ud på hhv. server og klient. Nederste lag er databasen (f.eks. MySQL). Øverste lag i modellen er brugergrænsefladen. Så her fastlægges, f.eks. hvilke farver og skrifttyper, man ønsker at anvende. Der er også her fokus på W3-consortiets anbefalinger skal inddrages endvidere krav til at opfylde (disabled people s wishes og lign.) Miderste lag bør designes ud fra en høj grad af modularitet - nedbryd krav om funktionalitet i delkrav som bør være funktionelle primitiver dvs. et modul som kun udfører 1 eller ganske få ting. Det bliver så under næste fase, Implementeringen, lettere at programmere hvert modul som f.eks. en php-funktion. Nederste lag er datalaget, i dette eksempel er det som hovedregel en MySQL database og I kan passende her i designfasen fastlægge kravspecifikationens ønsker om opbevaring af data i form at et E/R-diagram. Dette kan så under implementeringen danne grundlag for de CREATE statements, som skal til for at konstruere databasen. Dokumentation fra denne fase: Diagrammer og beslutninger (f.eks. E/R diagrammer -site-maps UML mv.) 4. implementering Nu skal resultatet af designfasen omsættes til xhtml, css, javascript, php, mysql etc. Det er nu vi skal oprette attributter og variable fastlægge hvilke typer hhv. xhtml-formvariable php-variable og mysql- attributter, der skal anvendes. Hjælpemidlerne til alt dette kommer fra designfasen hvor I jo på forhånd har fastlagt såvel de overordnede linjer og nogen gange en del detaljer. I står måske med et E/R-diagram hjælp til oprettelse af en database samt et site-map til oprettelse af php-scripts til at understøtte funktionaliteten Det er altså her funktionaliteten bliver født eller ført ud i livet. Eksempler: Hvordan logger man ind? Hvordan oprettes en ny bruger? Hvordan oprettes en superbruger? Hvordan slettes en bruger? Hvordan afspejler alt dette sig i databasen? Hvordan præsenterer vi et udtræk fra databasen for brugerne? Hvordan tager man backup af systemet? Der skal skabes muligheder for inputvalidering på såvel serversiden (php og Mysql) som klientsiden (javascript). Resultatet af denne fase er enten en færdig applikation eller en prototype. Men det skulle gerne være noget, der kan køre. Dokumentation fra denne fase er: Kildekode samt en URL, hvor prototypen kan udforskes. Side: 3/6
5. Afprøvning Afsnittet eller kapitlet om afprøvning eller test indeholder altid mindst 3 delafsnit: a. Strategi for testen b.beskrivelse af testen og c. Konklusion på afprøvningen. Strategi for testen eller afprøvningen. Her beskrives, hvad man vil afprøve og hvordan, og måske også noget om, hvad man ikke afprøver. Der findes 2 klassiske metoder for testning af programmer, blackbox- og whiteboks-afprøvning. I forbindelse med Web-programmering bør man også inddrage test af brugergrænsefladen i forskellige browsere. Whitebox-testen kaldes også for en skrivebordstest, fordi man gennemgår koden uden brug af en computer. F.eks. ved skrivebordet med den udprintede kode. Her gennemgår man alle if else og while-, do while og for- konstruktioner og overbeviser sig selv om logikken er på plads. Her kan man godt finde overflødige linjer af kode, som kan fjernes fra programmet uden, at funktionaliteten ændrer sig. F.eks., if ($x < 20 ) echo else if ($x >= 20) echo.. else echo $x er ikke hverken Eksemplet viser tydeligt, at enten er der noget galt med logikken (betingede sætninger) eller også er der en overflødig sætning. En white boks test dokumenteres med et skema, hvor man henviser til kildekoden med linjenummer og beskriver de ting, man har gennemgået. Black-boks testen. Her opfattes programmet som en sort kasse. Vi ved kun, hvad der skal puttes ind, og hvad der så forventes at komme ud i den anden ende. Vi har lavet et program, som til en given dato, spytter den korrekte ugedag ud. Vi har i strategiafsnittet, besluttet at teste, hvordan programmet opfører sig i en række tilfælde: En lovlig dato (15.11.2005), en ekstrem (29.02.2004) men lovlig dato, og ekstreme (32.12.2005) + (29.02.2005) ulovlige datoer, en dato før den gregorianske kalender blev indført osv.: Opstilling af et testskema: Test nr. Hvad testes Forventet resultat: Faktisk output Ok Screendump bilag: 1 15.11.2005 Tirsdag Tirsdag Ja 10 side 35 2 29.02.2004 Søndag Søndag Ja 23 side 51 3 32.12.2005 Ulovlig dato Søndag nej 19 side 42 4 29.02.2005 Ej skudår ulovlig Fejl i dato Ja 12 side 37 5 12.10.1206 Før kalenderen Fejl i dato ja..osv 6. Til al held ses tydeligt at test nr. 3 afslører en fatal fejl i programmet, og det må der følges op på. Nu skal man være glad fordi ens test har fundet en fejl, og det var jo netop formålet med at teste programmet. Husk: En test, - som ikke finder fejl, - er en mislykket test Læg mærke til hvordan hver testkørsel skal dokumenteres med enten output via print eller som her via screen dumps, skal kunne genfindes i bilagene. Unittest: Man indsætter "println" echo eller lignende i sin kode med det ene formål at dokumentere flowet i programmet. Det skriver ud til konsol eller fil og må gerne kunne disables. Side: 4/6
Hvis I indsætter disse fra starten, kan det bruges i debug sammenhæng. Det ville være rigtigt rart hvis I vil skrive deciderede "unit-tests", når og hvis denne facilitet er til stede i et konkret udviklingsværktøj/miljø - kunne f.eks. være client-side scripts med en masse "hardcodede" valg, der sammen med førnævnte log fra serveren kan dokumentere programmet. Den mest simple form for disabling er naturligvis omdannelse til kommentarer, og med nogen snedighed er det nok muligt at anvende find and replace både til enabling og disabling. Afprøvningen af brugergrænsefladen i forskellige browsere kan passende også opstilles i et skema, så bliver resultatet mere overskueligt: Internet Explorer FireFox Opera Netscape Chrome Til sidst i testkapitlet skal der være en selvstændig konklusion på afprøvningen med egen overskrift Konklusion på Test. Her beskriver I, hvad der virker, og hvad der ikke virker i programmet. I laver et resume af hvilke test I har gennemført og resultatet. Man kan aldrig garantere, at et program virker 100 % - der vil som regel altid være mindst en fejl tilbage. Dokumentationen skal være så præcis, at en anden kan gentage afprøvningen og kontrollere, om han får samme resultat. Kendte fejl En liste over fundne fejl og evt. forslag til, hvordan brugeren kommer uden om dem, og hvordan de kan rettes. En udokumenteret fejl trækker mere ned end en dokumenteret fejl. 6. Vedligeholdelsesvejledning Formålet med dette er at sætte andre i stand til at forstå systemet og dets virkemåde til bunds med henblik på en evt. senere revision af de principper, systemet baserer sig på. Dette må dog kun opfattes som en ufuldstændig liste med nogle "tommelfingerregler". Det bedste er, at holde sig formålet med dokumentationen for øje: systemets virkemåde skal kunne forstås af andre. I må ikke opfatte listen som udtryk for en rækkefølge, I skal følge - vælg den rækkefølge, I vurderer som værende mest naturlig for læseren. Vedligeholdelsesvejledningen skal dokumentere systemet, sådan at andre kan finde rundt i det og løbende vedligeholde det - d.v.s. rette småfejl, lave småændringer og -tilføjelser o.s.v. Vedligeholdelsesvejledningen skal indeholde følgende: A. Kørselsomgivelser Systemets krav til den maskine, der skal køre det: lagerkapacitet, programmel o.s.v. B. Diagrammer De endelige diagrammer med entiteter og attributter. Sitemaps med angivelse af asp eller php-scripts. Som notationsform kan alternativt benyttes UML. C. Systemets kildetekst Selve programteksten (SQL, xhtml, javascripts og asp/phpscripts). Af praktiske grunde skal den vedlægges som bilag. (henvis derfor til bilag) Linierne i programteksten skal være fortløbende nummererede indenfor hvert script. Side: 5/6
Kildeteksten skal være forsynet med linjenumre og passende kommentarer efter behov. Med passende kommentarer menes: - en kort forklaring af hver funktion - en kort forklaring af hver variabel og funktions formål med mindre dette er indlysende - indenfor hver funktion en kort forklaring af de programsætninger, der er væsentligst for funktionens virkemåde Pas på ikke at overkommentere! I behøver ikke at forklare noget, I vurderer oplagt eller selvforklarende. 7. Konklusion I konklusionen rundes hele projektforløbet af - hvad der gik godt hvad der gik mindre godt. Er prototypen tilfredsstillende. Hvad virker? hvad virker IKKE? Hvad kunne være gjort bedre med jeres nuværende know-how i bagagen? Forslag til fremtidige forbedringer af prototypen. Det kan være tilføjelse af ekstra services eller forfining af den eksisterende funktonalitet eller grænseflade. Rapporter med emner af mere teoretisk karakter skal som nævnt i starten have et afsnit 3. Syntese Hvad indeholder sådant et afsnit? Analysen i en teoretisk rapport vil kræse en del omkring problemformuleringen. Endvidere bør arbejdsprocessen også beskrives nøje i analysen. Når der arbejdes tværfagligt vil syntesen indeholde viden og færdigheder fra mere end et fag (f.eks. her både datakommunikation og [web]programmering men det kan også være andre områder/fag, der ligger til grund for tværfagligheden). Arbejdet skal være problemorienteret, undersøgende og udforskende og dette afspejles gerne både i analysen og i syntesen. Der må meget gerne såvel i analysen som i syntesen gives udtryk for en undren. Side: 6/6