Dokumentation med Kode og Flowchart

Fra HTX-Arduino
Skift til: navigering, søgning
Video med forklaring til kapitlet

Normalt vil dokumentation af kode blive fremstillet for at gøre koden tilgængelig for andre og lettere at vedligeholde.

I undervisnings-sammenhæng kan den samme dokumentation anvendes som en dokumentation for, at den der har udformet koden også har en forståelse af hvordan koden fungerer.

Kodeeksempler

Til dette kapitel er der nogle kodeeksempler man kan anvende. De er samlet i en ZIP-fil.

Grundelementer i Flowchart

Når man arbejder med flowcharts, så er der rigtig mange grundelementer man kan anvende til at udtrykke forskellige ting som det kan ses i figur 1, som er tager fra http://draw.io der er et glimrende værktøj til at tegne flowcharts med.

Mulige elementer til flowcharts i draw.io
Figur 1 Mulige elementer til flowcharts i draw.io.

I praksis kan man normalt nøjes med at anvende 4 forskellige elementer og så have pile imellem dem [1], hvor elementerne er som vist i figur 2.

De 4 forskellige grafiske elementer der anvendes til Flowchart
Figur 2 De 4 forskellige grafiske elementer der anvendes til Flowchart.

Den grundlæggende kode i Arduinoen

Hvis man ønsker at vise hele den kode der udføres i en Arduino, så vil overblikket se ud som vist i figur 3 med start efter reset (når der tændes for Arduinoen) hvor setup() koden udføres, og derefter gentages loop() koden.

Overblik over den samlede kode i en Arduino
Figur 3 Overblik over den samlede kode i en Arduino.

Som det kan bemærkes, så er der ikke nogen stop-handling i den samlede kode. Det er fordi programafviklingen fortsætter i det uendelige, eller indtil man slukker for Arduinoen.

God praksis for flowcharts

Det man normalt ser når man tegner flowcharts er at de svulmer op, så det bliver fuldstændigt uoverskueligt at finde ud af hvad programmet egentlig laver.

For at gøre flowcharts mere overskuelige, så er det en god ide at starte med at give et overblik som vist i figur 4, hvor der kun lige er skitseret hvilke forskellige ting programmet skal lave.

Den grundlæggende ide i det er at give overblikket over hvad det samlede program laver. Hvis man så også vil vise hvordan de enkelte dele er løst, så kan man lave flowcharts for hver enkelt del.

Dette falder godt sammen med god programmerings-praksis, nemlig at man forsøger at blokopdele koden, så hver del sørger for hver sin opgave i programmet.

Flowchart der viser overblikket over hvilke ting programmet skal lave
Figur 4 Flowchart der viser overblikket over hvilke ting programmet skal lave.

Når man har skabt overblikket ved at vise det overordnede gennemløb af koden i figur 4, så kan man gå ned i detaljer med hvordan de enkelte dele håndteres. Det kan for eksempel være delen med regulering, der kan vises som på figur 8.

Flowchart over reguleringens funktion
Figur 5 Flowchart over reguleringens funktion.

God kode

Når man skal skrive programkode der kan forstås af andre, og som andre måske skal kunne vedligeholde, så er der mange elementer der er vigtige at have fokus på.

Hvis man er en erfaren programmør, så er det ikke noget problem at starte med at forklare hvad koden skal lave fx ved hjælp af flowcharts. Det er noget anderledes i en undervisnings- sammenhæng, hvor man måske samtidigt er ved at lære at programmere. Her er der nogle tricks der kan være nyttige at kende.

Opdeling af programkode

I stedet for at starte med at løse et af problemerne i programmet, så kan det tit være smart at danne sig et overblik ved at dele koden op i nogle blokke. En måde at isolere tingene på er ved at placere de forskellige ting der skal laves i forskellige funktioner. Tager vi eksemplet fra flowchartet i figur 4, så kunne man programkode som vist i figur 6.

Programkode der sætter strukturen for et program
Figur 6 Programkode der sætter strukturen for et program.

Programkoden i figur 6 laver absolut ingenting, men den opdeler programmet i 4 forskellige dele, der løser hver sin del af programmets funktion. Herefter kan man stille og roligt begynde at løse hver sin del af programfunktionen, indtil man har det færdige program.

Variabel- og funktions-navne

Som det kan ses i figur 6, så er der brugt nogle funktionsnavne, der siger noget om hvad de forskellige funktioner skal løse. På samme måde skal man også navngive sine variabler med nogle sigende navne.

Det betyder ikke noget for funktionaliteten af programmet, der vil det virke fint hvis man kalder sine variabler for a, b, c og d, men det gør det svært at vedligeholde og forstå programkoden, så derfor skal anvende nogle mere sigende navne til variabler og funktioner, som eksemplerne vist i figur 7.

Eksempler på sigende variabelnavn
Figur 7 Eksempler på sigende variabelnavn.

Som man kan se i figur 7, så er det ret lange variabelnavne der er anvendt, og det kan tage lidt ekstra tid, når man skal skrive koden, men det man vinder på læsbarhed og forståelse af koden opvejer det mange gange.

Hvis man vil læse programkoden for reguleringen, så bliver det ret sigende ved at anvende gode variabelnavne, som man kan se det i figur 8.

Programkode der aflæser temperaturen og styrer reguleringen
Figur 8 Programkode der aflæser temperaturen og styrer reguleringen.

Det er en relativ simpel kode der er vist i figur 8, men det gør koden væsentlig lettere at forstå, når man har anvendt de variabelnavne man har.

Skal man understrege funktionen yderligere i koden, så kan man anvende kommentarer som beskrevet i næste afsnit.

Opdeling af variabelnavne

Som man ser det i eksemplet i figur 8, så er der variabelnavne der har en betydning med to ord. Da man ikke kan have mellemrum i variabelnavne, så er der her valgt at bruge camelCasing[2], [3]. Her er det lowerCamelCasing der er anvendt, som er en teknik hvor man har alle karakterer med lille, men 2. og 3. ord starter med stort bogstav inde i variabelnavnet. Nogle steder anvender man UpperCamelCasing, hvor også start-bogstavet er stort.

En anderledes måde at opdele variabelnavne på er med _ ved at sætte den mellem ordene, så raaMaaling vil blive til raa_maaling.

Hvilken måde man anvender er en smagssag, det vigtigste er at man er konsekvent med sine variabelnavne og funktionsnavne.

En sidste ting at bemærker omkring variabelnavne er at man ikke kan anvende danske karakterer æ, ø og å i variabelnavne. En mulighed er at bruge engelske udtryk, så forekommer de ikke. Alternativt kan man bruge den erstatningsform der er anvendt i raaMaaling, som står for rå måling - altså at å bliver til aa, ø bliver til oe og æ bliver til ae.

Kommentarer

Det er god praksis at beskrive hvad det samlede program laver og dets baggrund og evt. hvilke revisioner der er lavet i det (evt. bare hvem og hvornår det er skrevet), som eksempel kan kommentaren fra Blink-programmet se ud som i figur 9:

Start-kommentaren fra Blink-programmet
Figur 9 Start-kommentaren fra Blink-programmet.

Som det kan ses i figur 9 så starter en lang kommentar med /* og den afsluttes med */[4].

Som det kan ses, så indledes med en overordnet beskrivelse, derefter nogle tekniske detaljer, så en modifikations-historik med navne på og endelig en kildehenvisning til hvor man også kan finde noget om koden.

For at forklare de forskellige kodedele, så kan man bruge enkelt-linjes kommentarer. De starter med //[5].

Når man som begynder skal kommentere sin kode, så har man en tendens til at kommentere hver enkelt linje i programkoden, det fordi man kæmper med at forstå kodelinjerne, og derfor forklarer den enkeltes linjes funktion. Det giver sjældent mere overblik over programkoden, og bliver tit bare til ekstra forstyrrende fyld i koden. Hvis man har forklarende variabelnavne vil det meget sjældent være nødvendigt at kommentere på det niveau.

Hvis vi tager eksemplet med regulerings-funktionen, så kan den kommenteres som vist i figur 10, hvor hele funktionens virkemåde forklares i en linje inden funktionen.

Den kommenterede funktion til regulering af temperaturen
Figur 10 Den kommenterede funktion til regulering af temperaturen.

Kommer funktioner over 15-20 linjer, så kan man forsøge at opdele dem i nogle funktionsblokke, hvor man så kommenterer de enkelte deles funktion - det vil ikke være relevant i regulerings-funktionen, men skulle man gøre det med den, så kunne der gøres som i figur 11.

Funktion med forskellige dele kommenteret for sig
Figur 11 Funktion med forskellige dele kommenteret for sig.

Som det er fremhævet skal man passe på med at man ikke kommenterer for meget i sin programkode - der skal være kommentarer, men det er meningen at de skal forklare funktionen af det programkoden udfører, ikke hvad de enkelte programlinjer laver.

Hvad kommer først?

Man kan diskutere meget om man skal starte med at lave et flowchart eller om man skal starte med at skrive programkode.

Erfaringen viser at hvis man er i gang med at lære at skrive programkode, så giver det ikke så meget mening at skulle lave flowcharts først, da man alligevel ikke kan “oversætte” flowcharts til programkode, når man ikke er inde i syntaksen for programkoden.

En anden ulempe ved at starte med at lære flowcharts inden man lærer at skrive programkode er, at man ikke er inde i den sekventielle tankegang der ligger i programkode. Som bruger oplever man at programmer kan gøre ting samtidigt, men når man arbejder i programmer, er man nødt til at tænke på at programmet løser en ting ad gangen, inden det går videre til den næste ting. Den læring sker når man kommer til at analysere programkode ved at hånd-teste koden (læse og regne ud hvad der sker én linje ad gangen), denne læring er god at starte i når man skal lave flowcharts.

Eksempler

Det er altid farligt at komme med et eksempel på en dokumentation, da det kan blive for voldsomt i en læringsproces når man ser en færdig dokumentation.

Det kan også være farligt at man kan komme til at betragte sådan en rapport som en skabelon, hvor et anderledes projekt måske slet ikke passer ind i.

Her er alligevel et bud, som kan være dækkende for flere fag, men slet ikke fuldstændig opremsning af alle dokumentationsformer.

Rapport om et Ur med TV-timer bygget omkring Arduino Rapporten har fokus på flere fags dokumentationstraditioner, Teknologi B, Programmering C og Teknikfag A

Referencer