23 Dokumentere og dele arbeidet

I alle prosjektene har du dokumentert det du har laget. Her lærer du flere verktøy for å dokumentere og dele arbeidet. Bruk bestillings-appen fra Prosjekt 4, eller et annet prosjekt. Lagre alt i mappen kap23-dokumentere.

23.1 Kommentarer i HTML, CSS og JavaScript

kanelsnurr-bestilling/skript.js
// Bestillings-app for Kafé Kanelsnurr
// Laget av Amira Ali, 1IMA, mars 2027

// Legger varen med indeks i i kurven.
// Ligger varen der fra før, øker vi antallet i stedet,
// slik at kurven aldri har to linjer med samme vare.
function leggIKurv(i) {
  ...
}

En kommentar forklarer koden for den som skal lese den senere, og det er ofte deg selv. Den beste kommentaren sier hvorfor, og ikke det samme som koden sier fra før.

Språk Kommentar
HTML <!-- En kommentar -->
CSS /* En kommentar */
JavaScript // En kommentar på én linje
SQL -- En kommentar på én linje

Nedenfor ser du fire kommentarer til kodelinja kurv = []; i funksjonen sendBestilling.

Kode A
// Setter kurv lik en tom liste
Kode B
// Tømmer kurven, slik at neste kunde begynner på nytt
Kode C
// Kurv
Kode D
// Fikset denne nå, virker!!
  1. Hvilken kommentar hjelper mest for en som skal endre appen? Hva er problemet med hver av de andre?
  2. Gå gjennom skript.js i prosjektet ditt. Har hver funksjon en kommentar som sier hva den gjør? Skriv det som mangler.
  3. Finn ett sted i koden der du har gjort noe som ikke er lett å forstå. Skriv en kommentar som forklarer hvorfor.
  4. Finnes det kommentarer som bare gjentar koden? Fjern dem.

Kode som er vanskelig å forklare, kan ofte bli lettere å lese med bedre navn. Før du skriver en lang kommentar, prøv å gi variabelen eller funksjonen et navn som sier det samme.

23.2 En README-fil i Markdown

kanelsnurr-bestilling/README.md
# Bestillings-app for Kafé Kanelsnurr

En app der kundene kan bestille mat og drikke for å ta med.

## Slik starter du appen

Åpne `index.html` i en nettleser.

## Filer

- `index.html` – siden
- `stil.css` – utseendet
- `skript.js` – menyen og funksjonene

## Slik endrer du menyen

Menyen står øverst i `skript.js`. Se **dokumentasjon.html**.

Laget av Amira Ali, 1IMA, 2027.

En README-fil forteller kort hva prosjektet er, og hvordan man bruker det. Den skrives ofte i Markdown, der du merker opp teksten med tegn i stedet for tagger. Filen slutter på .md.

Markdown Blir
# Overskrift en overskrift på nivå 1, som <h1>
## Overskrift en overskrift på nivå 2, som <h2>
- punkt et punkt i en punktliste
1. punkt et punkt i en nummerert liste
**fet** fet tekst, som <strong>
*kursiv* kursiv tekst, som <em>
`kode` kode
[tekst](adresse) en lenke
  1. Les README-filen ovenfor. Hvilke HTML-elementer svarer til hver del?
  2. Lag README.md i mappen til prosjektet ditt.
  3. Se på filen med forhåndsvisning av Markdown. I mange editorer finner du det ved å høyreklikke på filen. Ser det ut som du ventet?
  4. Gi README-filen til en medelev som ikke har sett prosjektet. Klarer hun å starte appen og endre menyen uten å spørre deg?

23.3 Testtabell og testrapport

Nr. Test Forventet Resultat Rettet
1 Legg til én kanelsnurr 1 × Kanelsnurr, totalt 42 kr OK
2 Legg til kanelsnurr to ganger 2 × Kanelsnurr, totalt 84 kr To linjer med 1 × Kanelsnurr Søker i kurven før push
3 Send med tom kurv Melding, ingen ordrenummer Ordrenummer 101 Sjekker kurv.length
4 Fjern den siste varen Linja forsvinner OK

Kolonnen Rettet viser hva du gjorde med feilene. En testrapport er en kort tekst som oppsummerer testingen: hva som er testet, hvilke feil du fant, og hva som ikke virker ennå.

  1. Les tabellen. Hva skulle utvikleren ha gjort etter at test 2 og 3 var rettet?
  2. Hvorfor er det like viktig å skrive ned feilene du har rettet, som det som virket med en gang?

Gode tester sjekker også grenseverdiene, altså verdiene der programmet skifter oppførsel, som i oppgave 11.4. Test også det brukeren ikke skal gjøre: tomme felt, negative tall og tekst der det skal stå et tall.

  1. Lag en testtabell med minst ti tester for prosjektet ditt. Minst tre av dem skal teste feil bruk eller grenseverdier.
  2. Gjennomfør testene, og skriv en testrapport på fire til seks setninger.

Når du har rettet en feil, må du teste alt på nytt, og ikke bare det du rettet. En endring ett sted kan lage en ny feil et annet sted.

23.4 Skjermbilder og skjermopptak

Maskin Skjermbilde av en del av skjermen Skjermopptak
Windows

Klippeverktøyet, velg opptak
Mac

Chromebook , tasten for å vise vinduer det samme verktøyet, velg opptak

Et skjermbilde viser hvordan appen ser ut, og et kort skjermopptak viser hvordan den brukes.

  1. Ta et skjermbilde av appen din i mobilvisning, og et i et fullt vindu. Legg dem i mappen bilder.
  2. Legg skjermbildene inn i dokumentasjon.html med en god alternativ tekst.
  3. Ta opp en video på under ett minutt som viser en bestilling fra start til slutt. Planlegg hva du skal vise før du begynner.
  4. Utviklerverktøyene i nettleseren kan ta skjermbilde av en hel side, også det som er nedenfor vinduet. Finn ut hvordan.

Se over skjermbildet før du deler det. Fjern navn, e-postadresser, faner og varsler som ikke hører til prosjektet. Bruk oppdiktede data når du viser appen.

23.5 Ta vare på tidligere versjoner

Mappe
prosjekter
├── kanelsnurr-bestilling
├── versjoner
│   ├── kanelsnurr-2027-03-04-meny-virker.zip
│   ├── kanelsnurr-2027-03-07-kurv-virker.zip
│   └── kanelsnurr-2027-03-11-levert.zip
└── endringslogg.md

Det hender at du ødelegger noe som virket. En enkel måte å ta vare på tidligere versjoner er å lage en ZIP-fil av mappen hver gang noe viktig virker, med datoen i filnavnet.

endringslogg.md
# Endringslogg

## 2027-03-07
- Kurven slår sammen like varer
- Totalprisen vises

## 2027-03-04
- Menyen vises med alle varene fra kafeen
  1. Hvorfor står datoen først i filnavnet, og på formen år-måned-dag?
  2. Lag en endringslogg for prosjektet ditt, med de viktigste endringene så langt.
  3. Finn ut om skytjenesten skolen bruker, har versjonshistorikk. Hent fram en eldre versjon av en fil.

Utviklere bruker egne verktøy for versjonskontroll, som holder styr på hver eneste endring i et prosjekt. Ideen er den samme: Ta vare på en versjon hver gang noe virker, og skriv kort hva du har endret.

23.6 Levere og dele et nettsted

For å dele et nettsted på nettet må filene ligge på en webserver, en datamaskin som sender filene til den som ber om dem. Skolen har kanskje et sted der du kan legge ut nettsider.

Sjekk før du deler Hvorfor
Forsiden heter index.html serveren viser den når noen går til adressen
Alle adresser er relative stier adresser som C:\Users\... virker bare på din maskin
Filnavnene har små bokstaver, uten mellomrom og uten æ, ø og å mange servere skiller mellom store og små bokstaver
Alle bildene har du lov til å bruke du er ansvarlig for det du legger ut
Det står ingen personopplysninger på siden det du legger ut, kan alle se, og det er vanskelig å fjerne
Siden er testet på mobil og med tastatur de fleste besøker siden på mobil
  1. Gå gjennom prosjektet ditt med tabellen ovenfor. Rett det som mangler.
  2. Spør læreren om skolen har et sted der du kan legge ut nettstedet. Legg det ut, og test adressen på mobilen din.
  3. Hvem skal kunne se nettstedet ditt? Er det noe på siden du ikke vil at alle skal se?
Spør KI

Jeg skal levere et nettsted til en kunde. Her er README-filen og testrapporten min: [lim inn teksten]. Ikke skriv dem om. Si hva en kunde som ikke kan programmere, kan komme til å lure på etter å ha lest dem.

Oppsummering

I dette kapitlet har du dokumentert et prosjekt med kommentarer, en README-fil og en testrapport. Du har tatt skjermbilder og skjermopptak, tatt vare på tidligere versjoner med en endringslogg, og gjort nettstedet klart til å deles.

Dokumentasjon av et prosjekt

Del Hva den inneholder Hvem den er for
Kommentarer hva funksjonene gjør, og hvorfor koden er som den er den som skal endre koden
README.md hva prosjektet er, hvordan det startes, og hvilke filer det har den som åpner mappen
dokumentasjon.html bestillingen, planen, valgene, testingen og kildene kunden og læreren
Testrapport hva som er testet, feil som er funnet og rettet kunden og læreren
Endringslogg hva som er endret, og når deg selv og den som overtar

Merk deg følgende:

  • En god kommentar forklarer hvorfor, og ikke det samme som koden sier.
  • I Markdown gir # en overskrift og - et punkt i en liste.
  • Test grenseverdier og feil bruk, og test alt på nytt etter at du har rettet en feil.
  • Se over skjermbilder og nettsteder før du deler dem.

Oppgaver

Oppgave 23.1

Skriv om README-filen nedenfor i Markdown, med overskrifter, en liste over filene og en lenke til dokumentasjonen.

les-meg.txt
Quiz om fyret. Laget av Jonas Berg 2027. Åpne index.html for å starte. Filene er index.html som er siden, stil.css som er utseendet og skript.js med spørsmålene. Spørsmålene står øverst i skript.js. Mer informasjon i dokumentasjon.html.

Oppgave 23.2

Velg en funksjon fra et program du har laget i Del 4. Skriv tre kommentarer til den: én som bare gjentar koden, én som er for vag, og én som er god. Forklar forskjellen.

Oppgave 23.3

Lag en testtabell for funksjonen billettpris(alder) fra oppgave 17.4. Ta med alle grenseverdiene og minst to eksempler på feil bruk.

Oppgave 23.4

Ta et skjermbilde av en side du har laget, og legg det inn på en side med en god alternativ tekst. Forklar hva du fjernet eller beskar før du delte det.

Oppgave 23.5

Forklar hvorfor det er lurt å ta vare på tidligere versjoner, selv om du aldri trenger dem.

B-oppgaver

Oppgave 23.6

Undersøk mer Markdown: tabeller, kodeblokker og bilder. Lag en README-fil for Prosjekt 3 som har med et skjermbilde, en tabell over scenene og et kodeeksempel.

Oppgave 23.7

Lag en mal for dokumentasjon.html som du kan bruke i alle prosjektene dine, med overskrifter, en tom kravliste og en tom testtabell.

Oppgave 23.8

Bytt prosjekt med en medelev. Les README-filen og dokumentasjonen, og test prosjektet med testtabellen hennes. Skriv en kort tilbakemelding: Hva var tydelig, hva manglet, og fant du feil hun ikke hadde funnet?

Oppgave 23.9

Undersøk hva versjonskontroll er, og hvorfor utviklere bruker det. Sammenlign med ZIP-filer og endringslogg. Hvilke problemer løser versjonskontroll som ZIP-filer ikke løser, når flere arbeider på det samme prosjektet?