Föreläsning 12 - Dokumentering, testning och kryptering

Dokumentering
Testning
Kryptering, gästföreläsare: Mikael Goldmann

Dokumentering

Varför dokumenterar man kod? Måste man alltid dokumentera kod? Om man vet att koden man skriver ska köras mer än en gång av någon annan än en själv behövs någon form av dokumentation. I stora system finns flera typer av dokument som ska skrivas.

Man skriver ofta kommentarer i programkod. Väl skött är den ovärderlig vid själva utvecklingen. I ett större projekt med många inblandade kan inte alla ta del av all kod eller ens någon kod alls. Därför måste också ytterligare dokumentation skrivas.

Man kan säga att alla dokumentation skrivs för att fungera som beslutsunderlag och/eller beskrivning av systemet på någon nivå.

Beslutsunderlag

Dokument utgör ofta beslutsunderlag till om projektet ska få fortsätta eller t.o.m. om det överhuvudtaget ska få starta. Natulrigtvis används dokument även vid mindre beslut.

Beskrivning

System som inte är dokumenterade går varken att använda eller underhålla. Vid slutlig leverans måste systemet vara fullständigt dokumenterat. Det är inte bara slutanvändaren som behöver dokumentation. Även inom projektet behöver olika komponenter, kod, delsystem och utvecklingsverktyg dokumenteras. Tänk på att den kod du skriver kanske behöver underhållas i flera decennier framöver.

Dokumenttyper

Det finns massor av olika typer av dokument som skrivs före, under och efter ett stort mjukvaruprojekt. Det skiljer sig naturligtvis lite mellan olika organisationer och projekt. Här är några typer som ofta finns med:

Systembeskrivning (på många olika nivåer)
Designdokument (detaljerade beskrivningar av de i projektet utvecklade programmen)
Leveransdokument (delleveranser och slutleveranser)
Bör innehålla bla en beskrivning av kända begränsningar och fel.
Bruksanvisningar
Kvalitetsdokument (ibland enligt någon vedertagen standard)

Kodkommentarer i Python

I Python skriver man funktionskommentarer (och klasskommentarer) direkt efter deklarationen. Man skriver kommentaren som en vanlig flerradssträng (inleds och avslutas med tre dubbelfnuttar """), tex:

def print_schedule(data):
	"""
	The function prints the schedule on stdout (standard out)
	data - a dictionary containing the schedule
	"""
	
	# Här kommer koden

Med modulen pydoc kan man sedan generera dokumentation, t.ex. i html-format.

Testning

Att testa sina program är en självklarhet. Annars vet man ju inte om de fungerar. Det är en sak att få sitt program att kompilera, en annan att sak att det verkligen gör det man vill att det ska göra.

Det är väldigt svårt att veta om man testat allt.

Kodtestning i python

Det finns en modul i python - doctest - som kan tolka tester i kodkommentaren. Man kan klistra in en testkörning av funktionen och den kommer att utföras. Här följer ett exempel på get()-funktionen i en köklass (se labb 2).

class Queue:
    "En köklass"
    
    # Kod i köklassen

    def get(self):
        """
        Returnerar och tar bort det som står först i kön.
        
        >>> q=Queue()
        >>> q.put(5)
        >>> q.put(3)
        >>> 5==q.get()
        True
        """

	# Här börjar koden i funktionen

        retnode=self.head
        if self.head==self.tail:
            self.head=self.tail=None
        else:
            self.head=self.head.next
        return retnode.info

     # Mer kod i köklassen

def _test():
    import doctest
    doctest.testmod()

if __name__ == "__main__":
    _test()

Kör vi funktionen _test() får vi inget svar. Det är normalt eftersom testet fungerar. Vore köklassen felaktigt implementerad så get() returnerade något annat än 5 skulle vi få följande svar:

**********************************************************************
File "queue.py", line 28, in __main__.Queue.get
Failed example:
    5==q.get()
Expected:
    True
Got:
    False
**********************************************************************
1 items had failures:
   1 of   4 in __main__.Queue.get
***Test Failed*** 1 failures.

Utöver att detta ger en möjlighet att testa sin kod är det också bra att använda ett anrop för att beskriva användningen.

Unit test

Det behövs många tester för att testa stora system och alla dessa går inte att skriva i kodkommentarer för då blir inte kommentaren läslig. Istället skriver man egna testklasser som bara har till uppgift att testa en eller flera klasser i systemet. För att testa igenom hela systemet kör man sedan alla testfall i alla testklasser. I python finns ett paket - unittest - som man använder för detta.

Ett viktigt skäl till testning är att göra regressionstest, d.v.s. att kontrollera att den befintliga koden inte påverkas i oönskad riktning då man tillför eller ändrar någon annanstans. Om systemet är stort medför det ofta att många tusentals test måste göras varje gång något ändras i koden. Att automatisera testningen är nödvändigt.

Testdokument

Odokumenterade tester är värdelösa! Får man under utvecklingen av ett system en felrapport från ett test måste man snabbt kunna få veta vad för slags fel det är, helst så noggrant beskrivet som möjligt. All testkod måste alltså också dokumenteras så det är lätt att felsöka.

Kom ihåg att...

...det är lätt att skriva program som fungerar när användaren gör som man tänkt sig ... det är dock inte alltid fallet...