Program Dokumentation

Fra Holstebro HTX Wiki
Skift til: navigering, søgning

Formålet med at dokumentere programmer

Der er to lige gode grunde til at dokumentere sine programmer:

  1. Det er en metode til at udvikle programmerne mere struktureret
  2. Det er en måde at vise andre hvordan koden er opbygget / tænkt / planlagt

Den første grund hænger sammen med, at man sjældent kan overskue alle de funktioner et program skal have og endnu mindre hvordan man laver dem i programmet. Det at starte med at lave noget dokumentation kan være en god måde at bryde programmerings-processen ned i mindre dele.

Den anden grund er ud fra det, at en større kode kan være svær at overskue. Uanset hvilken grund man har til at kommunikere opbygningen af ens kode, så er dokumentation vejen frem. Gode grunde til at dokumentere kan være:

  • At andre personer skal kunne rette / vedligeholde koden.
  • At man selv skal kunne overskue koden på et senere tidspunkt, enten fordi man vil bruge dele af den, eller at man skal videreudvikle på den
  • At man skal bruge det som en aflevering (opgave eller eksamen).

Eksamens Journal

En speciel genre er Eksamens Journalen, som bygger på de principper der er beskrevet omkring dokumentation, men som også skal have lidt specielle krav opfyldt.

Programmer er ikke ens

Der findes i dag programmer i mange forskellige sammenhænge:

  • Styresystemer
  • Applikationsprogrammer (som word og excel)
  • Internetapplikationer (indkøbskurv / gmail / nemID mm.)
  • Drivere til hardware
  • Styringen af apparater (vaskemaskine / mikrobølgeovn / vejrstation)

Der findes mange flere kategorier, men pointen er, at med de mange forskellige typer programmer, så vil der også være mange forskellige måder at dokumentere dem på.

Sagt lidt omvendt, så er det en fordel at vælge sin dokumentationsform efter hvilken type program man udvikler.

Hvor starter man?

Det er så igen afhængigt af hvilken type program man udvikler, men også hvordan man vil gribe problemet an - hvilken tilgang har man til programmerings-udviklingen.

Et typisk sted at starte vil være med en brugerflade dokumentation, der angiver hvordan man regner med at programmet skal se ud, men også noget om hvordan det skal betjenes.

Man kan også starte med (eller selvfølgelig fortsætte med) at dokumentere sit programflow, altså den sekvens der skal laves i programmets forskellige dele. Det kan typisk være at at man skal udvikle en algoritme til at løse et specifikt problem, men det kan også være fordi man bare vil gøre det klart, hvad programmet skal lave, og hvornår det skal lave det. Der findes forskellige teknikker til at dokumentere flow:

  • Pseudokode der er en simpel tekstlig beskrivelse, med minimale grafiske virkemidler.
  • Flowchart der er en gammel teknik med gode visuelle virkemidler - kan også dokumentere ustruktureret kode.
  • NS-diagram En halv-grafisk metode, der kun kan dokumentere struktureret kode.

Hvis man skriver programmer med en objektorienteret tankegang, så vil det være en fordel at anvende et værktøj som UML eller i hvert fald dele af det til at dokumentere sine klasser og objekter.

En anden ting der også kan være godt at dokumentere er de variabeler og datastrukturer man anvender - nogle kan være ganske indlysende, og nærmest dokumenteret ved at de har et sigende navn, men andre mere komplicerede strukturer kan være sværere at gennemskue, når man skal læse og, mest af alt, rette i et program. Det kan derfor være en god ide at forklare indholdet af de centrale og vigtigste variabler, og specielt dem der kan have en kompleks struktur.

Uanset hvor man starter, så er det en klar fordel at man starter med dokumentationen, og og så udvikler programmet ud fra det. Det er dog sjældent at man kan færdiggøre hele dokumentationen inden man starter med at skrive kode. Det er så vigtigt at man tilpasser sin dokumentation, så den stadig dokumenterer det der er programmets funktion.

Vedligeholdelse af dokumentation

Ligesom det er vigtigt at vedligeholde sine programmer, så de hele tiden har de funktioner man ønsker, og de lever op til de krav der bliver stillet. Lige så vigtigt er det at de rettelser / udvidelser man laver bliver afspejlet i dokumentationen. Ellers mister den sin værdi.

Afslutning af dokumentation

Som med alle andre projekter kan det være en god ide at opsummere om programmet opfylder det man ønskede fra starten (en form for konklusion).

Selvom man afslutter programmeringen, så kan det jo stadig være at man har ideer som man bare ikke lige har tid til / mulighed for / evner til at løse, men disse ideer kunne man dokumentere i en perspektivering.