PK, AD1: Kodningsstandard

Företag som bedriver god utveckling av programvara har kodkonventioner - på samma sätt kan det användas i kurser i programmering och mjukvaruutveckling. Kraven i denna kodkonvention har utformats som verktyg att hjälpa och vägleda ditt tänkande före och under programmeringen - inte som ett ytterligare hinder efter att du lyckats färdigställa ditt program.

Reglerna underlättar också förståelsen för ditt program hos andra - t.ex. lärare och assistenter som skall bedöma dem.

Att sluta använda dessa goda vanor efter att du avslutat kurserna som kräver dem är att göra dig själv en otjänst. En kompetent och erfaren programmerare kan förstås göra specifikationer i huvudet, men det är till föga hjälp om hon ser tillbaka på programmet en tid senare eller om någon annan måste arbeta med programmet. Ingen ingenjör arbetar på en konstruktion utan en kravspecifikation!

Specifikationer

Varje funktion skall föregås av en kommentar med dess specifikation. Det gäller oavsett om den är deklarerad lokalt eller globalt, är "stuvad" (curried) eller inte, är angiven i uppgiftsbeskrivningen eller påhittad av dig.

Det enda undantaget från ovanstående gäller anonyma funktioner som ges som argument till en annan funktion. Där slipper du skriva specifikation, men å andra sidan skall en sådan funktion vara mycket enkel. Om den inte är det så skall du inte använda en anonym funktion utan namnge den.

Kommentaren skall vara utformad på följande sätt:

(* funktionsnamn argument
   TYPE: argumenttyp -> resultattyp
   PRE:  ... förvillkor (på argumenten) ...
   POST: ... eftervillkor (beskrivning av resultatet) ...
   EXAMPLES: ... representativa exempel på anrop och resultat ...
*)

Om du använder ackumulatorvariabler (som t.ex. i svansrekursion), se till att PRE inte kräver att dessa skall ha ett konstant värde. Det kanske gäller för första anropet, men inte i de rekursiva anropen.

I PRE och POST finns ingen anledning att ange typerna hos argument eller resultat eftersom detta redan framgår av TYPE-raden.

I POST räcker det att ange ett uttryck för värdet. Att t.ex. skriva ut "Det beräknade värdet är..." är onödigt.

Observera att specifikationen normalt inte kan vara riktig om inte samtliga argument förkommer i POST (eller i SIDE-EFFECTS, om det är aktuellt - se nedan).

Varje värde i en abstrakt datatyp eller modul skall föregås av en kommentar med dess specifikation. Kommentaren skall vara utformad på följande sätt:

(* valuenamn
   TYPE:  typ
   VALUE: ... beskrivning ...
*)

Beskrivningarna skall ges i klartext. Specifikationer skrivs vanligen oberoende av programspråket, så långt möjtligt. En lämplig blandning av klartext och vanlig matematisk notation är normalt bäst. Skriv alltså 0 och inte 0.0. Om det finns möjlighet är ≠ bättre än <>, · är bättre än *.

Lösningen av en uppgift - vare sig det gäller på laboration, inlämningsuppgift eller tentamen där inte alla funktioner och värden har en specifikation med ovanstående innehåll kan komma att underkännas! Detta oberoende av ifall lösningen i övrigt skulle vara fullständigt korrekt.

Identifierare

Varje identifierare skall beskriva den funktion/värde den namnger.

Varje identifierare skall börja med liten bokstav. Om man vill ha flera ord i identifieraren så stapla dem på varandra och låt alla ord utom det första börja med stor bokstav. Använd inte understrykningstecken (`_') mellan ord.

Exempel:

   maxValue
   endOfTheGame

Rekursiva funktioner

Varje rekursiv funktion skall föregås av en kommentarrad som anger rekursionsvarianten. T.ex. så här:

  (* VARIANT: ... *)

Precis som PRE och POST så skall varianten referera till argumentnamnen i specifikationen, inte till argumentnamn i programmet. Anledningen är att varianten skall skrivas innan programmet konstrueras eftersom den avspeglar en designfråga. Dessutom är varianten inte en del av specifikationen, utan en del av ett argument för att programmet är riktigt. För en given specifikation kan man skriva flera olika program med olika varianter.

Lösningen av en uppgift - vare sig det gäller på laboration, inlämningsuppgift eller tentamen där inte alla rekursiva funktioner har en kommentar med ovanstående innehåll kan komma att underkännas! Detta oberoende av ifall lösningen i övrigt skulle vara fullständigt korrekt.

Sidoeffekter

Varje funktion med sidoeffekter skall ha en rad i funktionsspecifikationen som beskriver sidoeffekterna. T.ex. så här:

  SIDE-EFFECTS: ...

Lösningen av en uppgift - vare sig det gäller på laboration, inlämningsuppgift eller tentamen där inte alla funktioner med sidoeffekter har en kommentar med ovanstående innehåll kan komma att underkännas! Detta oberoende av ifall lösningen i övrigt skulle vara fullständigt korrekt.

Representationskonventioner och invarianter

Varje definierad datatyp (datatype och abstype) skall inledas med en kommentar om hur den skall användas och vilken invariant som gäller för den:

(* REPRESENTATION CONVENTION: ... beskrivning av hur typen representerar data ...
   REPRESENTATION INVARIANT:  ... egenskap hos representationen som alltid måste gälla...
*)

Indentering

Layout och indentering av funktionsdefinitioner skall göras på följande vis

fun namn mönster1 = uttryck1
    ...
  | namn mönsterN = uttryckN

Alternativt kan uttryck skrivas på raden efter mönstret:

fun namn mönster1 =
      uttryck1
    ...
  | namn mönsterN =
      uttryckN

Layout och indentering av if-then-else-uttryck skall göras på följande vis:

   ...
   if boolsktUttryck then
       uttryck1
   else
       uttryck2
   ...

Om ytterligare if-uttryck följer efter ett else bör layout och indentering göras på följande vis:

   ...
   if boolsktUttryck1 then
       uttryck1
   else if boolsktUttryck2 then
       uttryck2
   ...
   else
       uttryckN
   ...

Layout och indentering av case-uttryck skall göras på följande vis:

case uttryck of
  mönster1 => uttryck1
  ...
| mönsterN => uttryckN

Layout och indentering av let-uttryck skall göras på följande vis:

   ...
   let
       deklaration1
       ...
       deklarationN
   in 
       uttryck
   end
   ...

Layout och indentering av lokala deklarationer skall göras på följande vis:

   ...
   local
       deklaration11
       ...
       deklaration1N
   in 
       deklaration21
       ...
       deklaration2M
   end
   ...

Det exakta antalet blanktecken i indenteringen är inte viktig, men all indentering måste vara konsekvent, dvs varje uttryck inom "..." ovan måste börja lika långt från vänsterkanten utom där indenteringen skall ändras enligt ovanstående regler.

Indentering av andra uttryck än de som beskrivs ovan skall göras efter bästa förstånd. Titta gärna på program i kursboken och på OH-bilderna från föreläsningarna för ideer.

Exempel

(* myMax (a,b)
   TYPE: int * int -> int
   PRE:  (none)
   POST: the largest value among a and b
   EXAMPLES: myMax ( 2, 5) =  5
             myMax (~2,~5) = ~2
*)
fun myMax (a,b) =
    if a > b then
      a
    else 
      b
(* fact n
  TYPE: int -> int
  PRE:  n >= 0
  POST: the factorial of n
  EXAMPLES: fact 0 = 1
            fact 3 = 6
*)
(*  VARIANT: n *)
fun fact 0 = 1
  | fact n = n * fact (n-1)
abstype 'a stack = Stack of 'a list
(* REPRESENTATION CONVENTION:
   a stack with the elements in a list. Top element first, bottom element last.
   REPRESENTATION INVARIANT: (none)
*)
with
  (* emptyStack
     TYPE:  'a stack
     VALUE: the empty stack
  *)
  val emptyStack = Stack []
  (* push(v,S)
     TYPE : 'a * 'a stack -> 'a stack
     PRE:  (none)
     POST: the stack S with v added as top element
  *)
  fun push(v,Stack S) = Stack (v::S)
  ...
end
abstype 'b bsTree = Void
                  | Bst of (int * 'b) * 'b bsTree * 'b bsTree
(* REPRESENTATION CONVENTION:
   a binary search tree with key-value pair (k,s) in the root,
   left subtree L, and right subtree R is represented by Bst((k,s),L,R)
   REPRESENTATION INVARIANT:
   for Bst((k,s),L,R):
    - every element of L has a key smaller than k
    - every element of R has a key  larger than k
*)
with
  (* emptyBsTree
     TYPE:  'b bsTree
     VALUE: the empty binary search tree
  *)
  val emptyBsTree = Void
  ...
  (* exists(k,T)
     TYPE: int * 'b bsTree -> bool
     PRE:  (none)
     POST: true if T contains a node with key k, and false otherwise
  *)
  (* VARIANT: the number of nodes of T *)
  fun exists(k,Void) = false
    | exists(k,(Bst((key,s),L,R))) =
      if k = key then
	  true
      else
	  if k < key then
	      exists(k,L)
	  else
	      exists(k,R)
  ...
end