<URL:http://www.docs.uu.se/~perg/course/datakom/dv96/dbkrav.html>

Krav på program och dokumentation

Detta dokument handlar om hur ni ska skriva och dokumentera era program på kursen Datakommunikation I, och hur ni borde göra även annars.

Avsikten med dessa krav är att era program ska fungera, och i de fall de inte gör det (t.ex beroende på yttre faktorer) upptäcka att något gått fel, och vad. Avsikten är också att de program ni skrivit ska vara begripliga.

På de flesta kurser är uppgifter sällan större än att en ensam person kan överblicka hela problemet, men i industrin kommer man oftast att bara få jobba med en mycket liten del av system som ska underhållas i decennier. Då är det viktigt att man varit tydlig och dokumenterat väl.

Tyvärr sätts dock ofta likhetstecken mellan "mycket dokumentation" och "bra dokumentation". Bra variabel- och funktionsnamn räcker ofta långt, och ger ofta mer än flera A4-sidor med förklaringar.

God programmeringssed

Vad menas med "god programmeringssed"? Det är det något svårfångade begrepp som skiljer bra och dåligt skrivna program. De allra flesta icke-triviala program har buggar, skillnaden är oftast bara hur många och hur allvarliga. Skillnaden mellan väl och dåligt skrivna program är att den senare typen ofta inte ens märker att något går fel, och sällan gör något för att undvika ens uppenbara problem. Programspråket C och operativsystemet UNIX hjälper en tyvärr inte heller särskilt mycket, men ofta finns det sätt att begränsa skadorna.

Här följer några ganska rimliga krav på era program. Om ni försöker följa dem under hela utvecklingen av era program (dvs inte först när allt funkar), kommer ni eliminera många problem under utvecklingen.

Er enda chans att få godkänt för ett program som bryter mot detta, är om ni tydligt och mycket noga dokumenterar:

Dokumentation av program

Era program ska dokumenteras såväl internt som externt. Som ett minimum ska er interna dokumentation bestå av:

I princip ska det utifrån den interna dokumentationen kunna lista ut hur programmet fungerar. Man får givetvis anta att den som läser programmet är ganska van vid C-programmering och UNIX, men spåkula ska inte behövas såvida inte en bifogas programmet.

Extern dokumentation

Den externa dokumentationen ska ge en överblick över programmet, identifiera delarna och beskriva dem. Om ni är vana C-programmerare kommer ni att dela upp programmen i flera filer, och kanske låta klient och server dela på dem. Med en sådan uppdelning blir det lättare att identifiera delarna, eftersom det betyder att ni ofta bara behöver hänvisa till relevant fil.

Den externa dokumentationen ska innehålla:

Med endast den externa dokumentationen ska det gå att förstå hur ert program är upplagt och hur det sitter ihop, och hur det är tänkt att fungera. I princip ska inga kunskaper om C krävas av läsaren, även om viss man kan utgå från vis programmeringsvana.