Bar: /* NS-diagram */

2022-10-18T20:15:01Z

NS-diagram

← Ældre version		Versionen fra 18. okt. 2022, 22:15
Linje 87:		Linje 87:

	Eksemplet viser igen det samme forløb, som startede i blokdiagrammet.		Eksemplet viser igen det samme forløb, som startede i blokdiagrammet.
	\|valign="top"\|[[Image:NS-diag.png\|Eksempel på noget dokumenteret med NS-diagram]]		\|valign="top"\|[[Image:NS-diag.png\|Eksempel på noget dokumenteret med NS-diagram]]
	\|}		\|}

Bar: 1 version importeret

2022-10-18T19:59:17Z

1 version importeret

Ny side

Når man skal skrive et program skal man selvfølgelig dokumentere det. Det kan både være hvis man skal udgive koden så andre kan bruge den eller lære af den, men det kan også være for at sørge for, at når man om et par år finder koden igen og vil skrive videre, kan man igen komme ind i hvad det egentlig var man tænkte.

En god dokumentation starter med at give et overblik, og kommer gradvist ned i detaljerne for de enkelte dele af softwaren.

Denne side er mest rettet mod dokumentation af [[JAL]]-kode, til at fungere i en [[PIC]], men en del af teknikkerne har også generel karakter, så man kan bruge metoderne i andre sprog og andre programmeringsmiljøer.
=Struktur=
Når man dokumenterer sin software skal software gerne have en fornuftig struktur, hvis den skal være til at læse og senere udvikle på. Det betyder at dokumentation gerne skal følge den samme struktur, ellers er den ikke til at finde ud af. Der er forskellige måder afhængig af om det er et stort program med mange små moduler man laver, eller om det bare er en lille og simpel kode.

==Store Programmer==
Er projektet et stort program, skal man dokumentere hvad hvert enkelt lille modul skal lave, hvad det har af input og output. Det er så man kan danne sig et overblik af hvordan de forskellige dele af programmet kommunikerer med hinanden. Når man så har gjort det, kan man gå ind i selve koden og skrive kommentarer, så man kan se hvad de enkelte funktioner, løkker og procedurer gør.

==Små Programmer==
Selv ved meget små programmer kan det være en god ide med en overordnet oversigt, også selvom det kun involverer én fil. Man kan selvfølgelig gå ind i koden og dokumentere de forskellige funktioner, løkker og procedurer, men bare et program på 30-40 linjer vil have stor fordel af at blive dokumenteret ordentligt.

=Den indledende softwaredokumentation=
En god indledning til softwaredokumentationen kan være at beskrive hvad den software man vil lave egentlig skal løse i det givne projekt.

Hvis det handler om en temperatur-regulering, så kunne det være noget så enkelt som at beskrive, at softwaren skal kunne måle den aktuelle temperatur, og regulere ud på et varmelegeme for at fastholde den målte temperatur. Man kunne så supplere med at man skal kunne indtaste den ønskede temperatur, og man skal have en visning af temperaturen.

==Blokdiagram==
En god måde at supplere overblikket over softwarens funktion er ved at skitsere et blokdiagram, som vist her:
[[Image:Sw_blok.png|center|Eksempel på blokdiagram]]

Blokdiagrammet skitserer hvilke dele der er i softwaren, og hvordan de forskellige dele hænger sammen, altså hvad der kommer fra den ene blok i softwaren til den anden.

På dette punkt er det også vigtigt, at man ikke går for meget i detaljer - man mister bare overskueligheden, hvis man har meget mere end 6-7 blokke i diagrammet. Så er det bedre at slå nogle blokke sammen, og så lave et nyt blokdiagram over dem senere.

Man kan også komme ud for at der ikke er sammenhæng mellem blokkene, hvis softwaren skal løse flere uafhængige ting. Her kan det være vigtigt at skitsere hvilket princip man vil bruge for at løse det. Om man vil bruge [[polling]] eller [[interrupt]].

==Snitflader==
Som det er vist i blokdiagrammet, så er det smart, at det er præcist afgrænsede ting der komme fra en blok til en anden.

Til dette kan det være godt at definere snitfladerne. Det kunne være temperaturen, at den f.x. ligger i en variabel ved navn Temperatur af typen word, og at den er 0 ved 0 grader og at den er 2500 ved 25 grader, eller hvordan man ønsker at definere den. Det kunne også være praktisk at definere hvilket interval den kunne spænde over, f.x. fra 0 til 5000, altså fra 0 til 50 grader.

Setpunktet kunne så have defineret så det ligger i en variabel der hedder Setpunkt af typen word, og med samme værdimæssige betydning som temperaturen.

=Detaljeret dokumentation=
Når man har fået skitseret et overblik over hvad softwaren skal lave, så skal man have dokumenteret de forskellige dele af koden.

Der findes mange forskellige teknikker til dokumentation af software, og hvor anvendelige de er afhænger af hvad det er softwaren skal løse.

Et forløb i softwaren kan dokumenteres med pseudokode, flowchart eller en variant af flowchartet der hedder NS-diagram
==Pseudokode==
Princippet i pseudokode er at man beskriver i almindelig tekst, hvad det er koden skal udføre.

Hele teknikken i at anvende pseudokode er beskrevet på [[Pseudokode]]

Hvis man befinder sig i hvile-tilstanden af det ovenstående eksempel, hvor der skal måles temperatur, reguleres og styres på varmelegemet, der kunne en pseudokode for det se ud som følger:

Loop uendeligt
Mål Temperaturen
Styr varmelegemet efter temperaturen
Vis temperaturen

Alternativt kan man gå lidt dybere i det og beskrive:

Loop uendeligt
Mål temperatur
Er temperaturen under setpunktet?
tænd for varmelegemet
ellers
sluk for varmelegemet
Vis temperaturen

==Flowchart==
{|
|-
|valign="top"|En gammel klassisk måde at dokumentere flowet i et program på er ved hjælp af et flowchart, hvor der er en række standard-symboler der betyder handlinger, start og stop, input og output, forgreninger osv.

Som vist her til højre giver det et godt overblik over hvad der sker i programmet på en meget overskuelig form, men som dokumentation skal man passe meget på at man ikke laver sine flowcharts for store. Som man kan se i eksemplet her, så er hele indtastningsdelen blot illustreret som en blok, selvom det nok er den der kodemæssigt fylder langt det meste.

Eksemplet her illustrerer hele programmet som er skitseret i blokdiagrammet.

Et af problemerne ved at bruge flowchart er at det ikke er så let at tegne i f.x. word. Man skal typisk have et specielt program til det som visio, [http://dia-for-windows.en.softonic.com/ dia] eller andet.

|[[Image:flow-eksempel.png|right|thumb|Eksempel på et flowchart]]
|}

==NS-diagram==
{|
|-
|valign="top"|Et alternativ til flowcharts er at man tegner NS-diagrammer.

De kan tegnes ved hjælp af tabeller i word, så de er relativet enkle at gå til, det eneste lidt kryptiske er at få betingelser på, men her kan man gøre god brug af tegneværktøjet i tabeller.

Det kræver bare lidt tilvænning at læse NS-diagrammer.

Eksemplet viser igen det samme forløb, som startede i blokdiagrammet.
|valign="top"|[[Image:NS-diag.png|Eksempel på noget dokumenteret med NS-diagram]]
|}

==State-machine==
[[Image:state-diagram.png|thumb|right|eksempel på state-machine]]
Til at dokumentere en state machine bruger man et state-diagram som vist her.

Hele teknikken i at programmere en [[state-machine]] er dokumenteret på linket.

Anvendelsen af en statemachine er meget afhængig af hvilket problem man skal løse, men det kan være et meget effektivt værktøj til at løse ting der skal gøre forskelligt alt afhængigt af hvad f.x. en bruger har gang i.

Styrken ved en statemachine er at man kan isolere de enkelte dele relativt enkelt i koden, så det er lettere at holde styr på hvad der foregår i hvilke tilstande.

==Objekt-dokumentation==
Det skal først nævnes at [[JAL]] '''IKKE''' er et objektorienteret sprog.

Til at dokumentere objektorienterede programmer er [http://en.wikipedia.org/wiki/Unified_Modeling_Language UML] normalt en god standard, eller rettere det er mange gode standarder, for UML kan dokumentere rigtigt mange sider af programmeringen og på mange forskellige niveauer, lige fra det helt overordnede anvendelses-niveau, og helt ned i at dokumentere de enkelte objekter. Se beskrivelsen på det angivne link.

=Kommentering af Kode=
Hvis man fx kommenterer en funktion kan det gøres på flere måder. Hvis det er en tilstrækkelig simpel funktion vil det være nok at kommentere den med en linje der forklare hvad den gør.

Eksempel:
<source lang="jal">
function(input) -- man giver funktionen et tal, og så viser den hvad man får når man lægger 2 til det tal
var1 = input
var2 = var1 + 2
print var2
end function
</source>

Man kan også skrive kommentar til hver linje, men det kan nogle gange få koden til at se uoverskuelig ud. På den anden side kan det også blive nødvendigt, hvis det er meget avanceret programmering.

Eksempel:
<source lang="jal">
function(input) -- funktion med et enkelt input
var1 = input -- definering af variabel 1
var2 = var1 + 2 -- læg 2 til tallet
print var2 -- vis tallet
end function -- slut funktion
</source>

Hvornår de forskellige metoder skal bruges skal man selvfølgelig selv vurdere.

=Ting at huske=
* Start med at dokumentere det overordnede, så læseren får et overblik.
* Lav det af dokumentationen man kan, før man skriver softwaren, det giver normalt en bedre struktur i softwaren.
* Brug [[#Flowchart|Flowchart]], [[#Pseudokode|Pseudokode]], [[#State-machine|Statediagram]] eller en anden gængs standard til at lave den overordnede overblik med.
* Kommentarene og specielt den tilhørende dokumentation skal kunne forstås af nybegyndere, som udgangspunkt har man altid skrevet for lidt dokumentation.
* Skriv kommentarene mens man skriver koden, så man er sikker på at man ikke glemmer hvad koden gør.
* Husk at revidere og udvide dokumentationen efter man har skrevet softwaren, så dokumentationen passer sammen med det der reelt sker i softwaren.
* Overvej hvilken struktur koden har - dokumentationsformen kan godt være meget afhængig af hvad det er koden laver, og ikke mindst hvordan koden er opbygget.

[[Kategori:Software-beskrivelse]]

Softwaredokumentation - Versionshistorie

Bar: /* NS-diagram */

Bar: 1 version importeret