Programmeerproject 2015-2016

Eerste Bachelor Computerwetenschappen

Algemene richtlijnen en kwaliteitseisen
Titularis: Prof. Coen De Roover
Begeleidende Assistenten:
Christophe De Troyer (cdetroye@vub.ac.be)
Thierry Renaux (trenaux@vub.ac.be)
spaceinvaders@soft.vub.ac.be

1 Doelstelling
In dit programmeerproject is het de bedoeling de technieken die worden aangeleerd
in de cursus Structuur van computerprogrammas I in de praktijk te gebruiken om
software te ontwikkelen.
Een programmeerproject houdt meer in dan gewoonweg programmeren. Er wordt
zeer veel belang gehecht aan het ontwerp en de mondelinge en schriftelijke rapportering. De uiteindelijke implementatie moet gebeuren in Scheme. Bij de verdediging
wordt er in het bijzonder veel belang gehecht aan het ontwerp, de documentatie en
het correct gebruik van ADTs (Abstracte Data Types). Natuurlijk blijft de algemene
programmeerstijl ook uitermate belangrijk; is de code goed leesbaar, voldoet het aan
de kwaliteitseisen, is ze gedocumenteerd en performant?
Begin je project steeds met het uitdenken van abstracties, a.d.h.v. ADTs. Hou er
rekening mee dat, op een later punt, een andere programmeur (delen van) je code
zou moeten kunnen herbruiken en uitbreiden, zonder al teveel moeite. Het moet
bijv. mogelijk zijn ADTs achteraf te voorzien van een andere (eventueel meer perfomante) achterliggende implementatie, zonder dat dit de rest van de code aantast.
Uiteraard spreekt het voor zich dat ook de complexiteit van de afgeleverde applicatie
in rekening wordt gebracht. Wie meer hooi op zijn vork durft te nemen, wordt hiervoor beloond. Een te eenvoudig project daarentegen heeft weinig tot geen praktisch
nut omdat de problemen bij het ontwikkelen van software vooral te maken hebben
met het opdelen en beheren van complexiteit. De gouden regel om te slagen is: werk
regelmatig; liever elke week enkele uren dan alles in de laatste week voor een deadline
gedaan proberen krijgen.

Dit document is als volgt gestructureerd. Eerst wordt er uitgelegd wat we bedoelen
met implementatiefasen en hoe deze de agenda van het project bepalen (sectie 2).
Daarna geven we aan hoe een wetenschappelijk verslag geschreven moet worden
waarbij we focussen op de twee types van verslagen die binnen dit project moeten
opgeleverd worden (sectie 3). Tips over hoe je best te werk gaat tijdens het project worden gegeven (sectie 4) en wat een projectverdediging juist inhoudt, wordt
eveneens beschreven (sectie 5). We eindigen dit document met een opsomming
van kwaliteitsvereisten voor de code (sectie 6) en nog enkele handige tips (sectie 7).

2 Implementatiefasen en agenda
De concrete opdracht verschilt van jaar tot jaar. Typische voorbeelden zijn simulaties of spellen. Er wordt bij de opstart van het project een briefing gegeven over de
opdracht en een gedetailleerde agenda voor het projectverloop.
Het project verloopt in verschillende fases. Het aantal fases wordt aangepast aan de
concrete opdracht. Iedere fase bestaat uit een aantal stappen. Meestal zijn dit de
volgende stappen: (1) voorstudie, (2) implementatie, (3) coderapport en (4) verdediging. De eerste stap, een voorstudie, wordt niet noodzakelijk in elke fase verwacht;
dit hangt af van de concrete opdracht. Voor elke fase zal een concrete agenda opgesteld worden met concrete deadlines. Deadlines voor elke fase moeten gerespecteerd worden. Een projectdocument dat de concrete opdracht met de bijbehorende
fasen en concrete agenda bevat, is elk jaar beschikbaar.
Typische fasen zijn: een eerste fase waarin een kernfunctionaliteit moet gerealiseerd
worden en een tweede fase met uitbreidingen aan die functionaliteit of variaties. In
de eerste fasen wordt alleen interactie via scherm, toetsenbord en muis gevraagd.
Elke fase wordt enerzijds afzonderlijk beoordeeld. Belangrijk hierbij is dat problemen en tekorten in een bepaalde fase telkens bijgestuurd en opgelost kunnen worden in de volgende fase. Daarnaast wordt het geheel van het uiteindelijk ingediende
project nog eens in zijn totaliteit beoordeeld. Een concrete verdeling van de punten over de fases en het eindproduct hangt af van de projectopdracht en staat in het
projectdocument. Voor het eindresultaat wordt 70% van het cijfer bepaald door de
gerealiseerde functionaliteit en de kwaliteit van de code enerzijds, en 30% voor de
kwaliteit van de rapportering, de demonstratie en de mondelinge verdediging.
Alle berichten in verband met het project vind je op Pointcarr. Daar zal je op de
gepaste tijdstippen ook de lijsten met de data en uren voor de verdedigingen kunnen
vinden. Na het indienen van de eerste voorstudie krijg je een begeleider toegewezen.
Met vragen en problemen kan je steeds terecht bij je toegewezen begeleider.
Alle documenten moeten in PDF-formaat elektronisch ingediend worden op Pointcarr (via de aangemaakte opdracht; zie Opdrachten sectie op de PointCarr webpagina). MS Word, OpenOffice of andere bestanden worden niet aanvaard.

3 Verslagen
Deze sectie beschrijft wat een wetenschappelijk verslag in het algemeen inhoudt.
Ook worden enkele schrijftips gegeven, gebaseerd op [DOO en E. Mathijs, 2009]. De
laatste secties beschrijven de inhoud van het hoofddeel van een voorstudie en van
een coderapport.

3.1 Schrijven van een wetenschappelijk verslag

Zowel de voorstudie als het coderapport dat ingediend moet worden op het einde
van een fase zijn wetenschappelijke verslagen. Het schrijven van zo een verslag is
een belangrijk onderdeel van het werk van een wetenschapper. Een verslag moet
tot in de puntjes verzorgd zijn zowel wat lay-out betreft, als opbouw en structuur en
zeker wat betreft de inhoud.
Een verslag is een tekst maar geen proza. De bedoeling is om op een zakelijke en wetenschappelijke manier te rapporteren over de opdracht (voorstudie) en over jullie
code (coderapport). In deze sectie behandelen we eerst de algemene structuur van
een wetenschappelijk verslag en verduidelijken dit naar voorstudie en coderapport
toe.
Algemeen bestaat een verslag uit de volgende onderdelen:
1. Titelblad
2. Inhoudstafel (nuttig bij lange verslagen)
3. Inleiding
4. Hoofddeel
5. Besluit
6. Referenties (nuttig bij lange verslagen)

Titel Elk verslag moet een titel hebben. Kies deze zodanig dat het voor de lezer
duidelijk is over welk onderwerp het gaat. Ballastwoorden zoals Studie van of Onderzoek naar, afkortingen of merknamen worden best vermeden in de titel. Maak
voor jouw voorstudie en coderapporten een titelblad. Dit bevat de titel, jouw naam,
jouw rolnummer, jouw emailadres en jouw richting.

Inleiding Eerst wordt verduidelijkt wat het onderwerp is, in welke context het geheel kadert en wat de doelstellingen zijn. In tweede instantie licht je de opbouw van
het verslag toe en wijs je op samenhang tussen de verschillende delen. De bedoeling
is dat de lezer inzicht krijgt in het gestelde probleem en de aanpak ervan.

Het is nuttig om de inleiding pas te schrijven nadat de hoofdtekst geschreven is,

omdat het meestal dan pas duidelijk wordt hoe de gestelde problemen gedefinieerd
kunnen worden en wat de logische structuur van het werk is.

Hoofddeel Inhoudelijk is dit het belangrijkste deel van het verslag. Dit deel omvat
het eigenlijk gepresteerde werk. Niet enkel de antwoorden op de gestelde problemen en uitdagingen, maar vooral de gevoerde redenering die achter elk antwoord
schuilt, wordt in dit deel weergegeven. Afhankelijk of het om een voorstudie dan wel
een coderapport gaat, zal de inhoud van dit deel verschillen. Deze inhoud wordt in
meer detail besproken in sectie 3.3 voor wat de voorstudie betreft en in sectie 3.4
voor wat de coderapporten betreft.

Besluit In het besluit grijp je terug naar de probleemstelling uit de inleiding. Samen met de inleiding geeft het besluit een volledige samenvatting van de problemen/uitdagingen en de oplossingen. Je geeft ook aan in hoeverre je in je opzet geslaagd bent. Je kan hier ook opmerkingen kwijt over de gevolgde methode, eventuele
tekortkomingen of suggesties.

Referenties Alle bronnen die gebruikt worden om het verslag te schrijven, moeten vermeld worden in een referentielijst en aangehaald in de tekst. Hoe dit moet
gebeuren wordt beschreven in de volgende sectie.

3.2 Schrijftips
Zorg er voor dat je genoeg tijd neemt om je verslag te schrijven, dit is immers je
communicatie naar de assistenten toe. Is je verslag slecht, dan zal je code onherroepelijk op een andere manier bekeken worden. Met je verslag wil je de assistenten
laten begrijpen wat jij te rapporteren hebt. Zorg dat ze hun aandacht bij het onderwerp kunnen houden. Dit betekent bijv., dat lezers geen nutteloze aandacht moeten
besteden aan het trachten te interpreteren van een slecht opgebouwde zin of redenering. Je gebruikt wetenschappelijke taal op een correcte manier, zodanig dat de
betekenis niet verloren gaat. Hieronder staan enkele tips opgesomd over het gebruik
van het Nederlands:
Vervang in de tekst geen woorden of zinsdelen door symbolen.
Getallen in een tekst schrijf je liefst voluit, tenzij ze de waarde van een variabele
zijn.
Verklaar elk symbool.
Een goede zinsbouw en correct Nederlands zorgen voor een goed leesbare tekst.
Een wetenschappelijk verslag is allerminst een opeenvolging van formules,
cryptische codetaal, tabellen en figuren. Nederlandse zinnen moeten de formules, tabellen, figuren duiden en in een context plaatsen. Je kan bijv. uit
4

tabellen alleen, niet afleiden hoe de kolommen en rijen moeten genterpreteerd worden. De tekst die de tabellen omkadert letterlijk en figuurlijk moet
daarom helder en ondubbelzinnig zijn.
Maak zinnen niet te lang.
Ga na of de verbanden tussen de zinnen voldoende helder zijn.
Zeg het in kernachtige bewoordingen. Vermijd breedsprakerige en lege woorden als: aspect, facet, gebeuren, aard, mate van, in feite, in principe. Vermijd
omslachtige aanlopen als: Het is interessant te melden dat . . . , Opgemerkt
kan worden dat . . . , enz. Vermijd overbodige woorden zoals: enorm, fantastisch, gigantisch,. . . .
Schrijf het verslag niet in de ik-vorm.
Laat verwijswoorden correct verwijzen.
Gebruik niet de toekomende tijd.
Gebruik waar mogelijk de actieve vorm in plaats van de passieve vorm.
Vernederlands geen vreemde woorden. Is er geen Nederlands woord, plaats
het vreemde woord dan tussen aanhalingstekens.
Formuleer positief. Vermijd dubbele ontkenning.
In de rest van deze sectie wordt er uitgelegd hoe een inhoudstafel opgebouwd wordt,
hoe figuren, tabellen en referenties moeten geformatteerd worden. Deze tekst is
opnieuw gebaseerd op [DOO en E. Mathijs, 2009].

Inhoudstafel De meeste tekstverwerkingsprogrammas zijn in staat om een inhoudstafel automatisch te genereren, op voorwaarde dat in het document de juiste stijlen of opmaakprofielen werden gebruikt bij de verschillende onderverdelingen. Het
voordeel hiervan is dat paginanummers automatisch worden aangepast bij een wijziging in de tekst en dat geen titels worden vergeten. Bij de opmaak van de tekst
worden hoofdstukken en secties genummerd (Arabische cijfers). Lijsten van afkortingen, tabellen, figuren en referenties dragen geen nummer. Tracht geen indelingen te maken die verder gaan dan de vierde graad. Zo blijft ook de inhoudstafel
overzichtelijk. Op het eind van een titel volgt bij voorkeur geen leesteken.

Tabellen en figuren Alle figuren en tabellen moeten genummerd zijn in volgorde

van voorkomen in het werk. Bij elke tabel of figuur hoort een titel en een legende.
Kies duidelijke en betekenisvolle titels en geef voldoende verklaring in de bijhorende
legende. Voor tabellen staat de titel bovenaan en kan onderaan de tabel bijkomende
informatie vermeld worden. Voor figuren staat de titel onderaan, samen met de bijkomende informatie.
Tabellen worden niet gesplitst over twee bladzijden. Het is beter de hele tabel over
te brengen naar het volgende blad. Indien de tabel toch gesplitst wordt, gebeurt dit
5

op een logische plaats en wordt bovenaan het tweede deel vermeld dat het om het
vervolg van een tabel gaat.
Elke gebruikte tabel of figuur moet een verwijzing in de tekst krijgen. Deze verwijzing (Tabel 1.1, Tabel 1.2, . . . Figuur 1.1, Figuur 1.2, . . . ) komt altijd vr de eigenlijke tabel of figuur. Bij het verwijzen wordt de figuur of tabel ook altijd werkelijk
benoemd. Bij de meeste tekstverwerkingsprogrammas bestaat de mogelijkheid te
werken met labels en referenties, zodat alle verwijzingen automatisch worden aangepast als de figuur/tabel/formule van nummer verandert.

Referenties Alle werken die geraadpleegd werden om het verslag te schrijven, moeten worden vermeld in de referentielijst. Er zijn verschillende manieren om de bron
te vermelden in het geval van een tijdschrift of een boek. Het naamjaar-systeem
wordt aangeraden, dit is, tussen haakjes, de naam van de auteurs gevolgd door het
jaartal van publicatie. Bijvoorbeeld voor de syllabus van het vak Structuur van Computerprogrammas 1 wordt dit [Viviane Jonckers, 2011].
Voor het verwijzen naar Webpaginas vermeld je de auteur(s) die verantwoordelijk is
(zijn) voor de paginas en de datum waarop de website werd geraadpleegd. Vermeld
nooit de link naar de webpagina zelf in de tekst tenzij eventueel in een voetnoot. Een
voorbeeld van verwijzing naar website vind je in het begin van deze sectie.
De referentielijst wordt normaal alfabetisch gerangschikt volgens auteur en voor dezelfde auteurs chronologisch. Alle auteurs worden vermeld en onderling gescheiden
door een komma en een spatie. Na de auteurs volgt de datum van publicatie tussen
haakjes, gevolgd door een punt. Daarna volgt de titel van de publicatie, gevolgd door
een komma en dan de naam van het tijdschrift. Voor een boek volgt de titel van het
boek, met daarna naam en plaats van uitgeverij (gescheiden door komma en spatie). Tijdschriften worden aangeduid met hun volledige naam of volgens de officile
afkortingen. In elk geval moet consequent n systeem (tijdschriften voluit of afgekort) worden gebruikt. Na de naam van het tijdschrift volgt het volumenummer van
het tijdschrift gevolgd door een dubbel punt; na het dubbelpunt volgt de beginpagina van het artikel gevolgd door een en vervolgens de eindpagina gevolgd door
een punt.
Voorbeeld voor een tijdschrijft: Viviane Jonckers (2001). Titel van het artikel. Naam
van het tijdschrift, Volume(boekdeel): beginpagina-eindpagina.
Voorbeeld voor een boek: Viviane Jonckers (2003). Titel van boek. Uitgeverij, Plaats.
Voor Web-paginas worden eveneens alle auteurs vermeld, en worden de auteurs onderling gescheiden door een komma en spatie. Indien de auteur(s) niet gekend zijn,
dan wordt de organisatie achter de webpagina vermeld. Daarna volgt de datum van
publicatie tussen haakjes, gevolgd door een punt. Na de datum volgt de titel van de
webpagina; titels worden vermeld in de oorspronkelijke taal. De titel wordt gevolgd
door [on line]; daarna komt de naam van de uitgeverij. Tot slot volgt Beschikbaar
op URL [datum van opzoeking: dd/mm/yy]. Een voorbeeld van zo een verwijzing
vind je in de referentielijst van dit document.

3.3 Voorstudies
In je voorstudies probeer je zo goed mogelijk je onderwerp vast te leggen. Welke
functionaliteit moet het programma bevatten? Welke concepten (ADTs) moeten
hiervoor ontworpen en gemplementeerd worden? . . . .
Een goede truc is om een lijstje te maken van alle belangrijke zelfstandige naamwoorden die in je specificatie voorkomen. Probeer ze te beschrijven zoals je geleerd
hebt in de les. Denk in termen van wat het ADT moet kunnen, en welk gedrag het
moet hebben. Welke data moet het bijhouden? Je hoeft nog niet te specificeren HOE
je het gaat implementeren. Zeg vooral WAT er moet gebeuren. Per ADT vermeld je
in je verslag: de naam van het ADT, de data die dit ADT encapsuleert en de verschillende boodschappen die het ADT begrijpt. Voor de beschrijving van deze laatste
gebruik je best een tabel die per boodschap de volgende informatie bevat: de naam
van de boodschap, de verwachtte inputparameters, de verwachtte outputparameters, en eventueel een korte beschrijving.
Stel tenslotte een tijdschema voor jezelf op. Zeg voor elke week (vr de deadline)
wat je precies zal doen voor je project. Het is ook belangrijk dat je leert in te zien hoeveel tijd je besteedt aan welke soort taken; het is dus zeker geen ramp als je initeel
foutieve inschattingen maakt (dit is zelfs te verwachten).
Zorg ervoor dat je voorstudie een diagram met de afhankelijkheden tussen de verschillende ADTs en onderdelen van je project bevat. Dit afhankelijkheidsdiagram
verbindt alle ADTs en deelstukken waartussen interactie is, en beschouwt elke soort
relatie: o.a., referenties, communicatie, conceptueel verband,. . . Heel belangrijk hierbij is dat je duidelijk de relaties benoemt en GEEN vage namen (zoals is, heeft,
etc.) gebruikt, maar wel specifieke, concrete termen.
Dit alles schrijf je neer in het hoofddeel van het wetenschappelijk verslag dat de
voorstudie wordt. Dit verslag omvat maximum 5 paginas, en wordt elektronisch ingediend in PDF formaat op Pointcarr (via de aangemaakte opdracht; zie Opdrachten sectie op de PointCarr webpagina).
Per e-mail laten we iedereen zo snel mogelijk weten wat we van je voorstudie vinden.
De persoon van wie je deze e-mail ontvangt zal van dat moment je begeleider zijn
voor het project. Tijdens het verloop van het project richt je je dan ook tot deze
persoon voor al je vragen.
Een aantal concrete voorbeelden van voorstudies van vorige jaren zullen beschikbaar gesteld worden op Pointcarr, en zullen besproken worden bij de projectvoorstelling.

3.4 Coderapporten
In de coderapporten geef je een volledige stand van zaken. Je zegt welke doelstellingen wel en welke niet gerealiseerd werden, en ook wat je extra hebt toegevoegd. Je
verdedigt en evalueert de gemaakte keuzes. Eventueel schets je wat er verder in het
7

project zou moeten gebeuren om de doelstellingen te realiseren. Het rapport schetst

ook welke andere uitbreidingen zouden kunnen gemaakt worden.
Het rapport wordt samen met de broncode (inclusief inhoudstafel van de bronbestanden) in PDF formaat ingediend op PointCarr (via de aangemaakte opdracht;
zie Opdrachten sectie op de PointCarr webpagina).
Het hoofddeel van dit type verslag bevat volgende punten:
Geef uitleg over de manier waarop je het project hebt aangepakt (de verschillende deelstukken, ADTs, algoritmes, . . . ). Geef opnieuw een beschrijving van
de ADTs zoals reeds besproken in de vorige sectie.
Zorg ervoor dat je verslag een diagram met de afhankelijkheden tussen de verschillende onderdelen van je project bevat.
Refereer naar plaatsen waar je oplossingen hebt gevonden (cursussen, contactpersonen, andere applicaties, literatuur, . . . ).
Vermeld welke hulp- en testapplicaties je zelf gemaakt hebt. Indien je gebruik
maakt van reeds bestaande code, vermeld dan steeds de bron.
Evalueer de keuzes die gemaakt werden. Schets alternatieven en evalueer ze
met de ervaringen die je nu hebt opgedaan.
Schets het tijdschema van het eigenlijke verloop van het project, en vergelijk
met het vooropgestelde schema. Zoals reeds vermeld zullen er hoogstwaarschijnlijk verschillen zijn tussen het oorspronkelijk schema (zoals vermeld in
de voorstudie) en het uiteindelijke schema dat je gevolgd hebt; verberg deze
niet, maar geef een verantwoording (+ geleerde lessen) waar er zich grote verschillen voordoen.
Het rapport wordt samen met de broncode (inclusief inhoudstafel van de bronbestanden) in PDF formaat ingediend via PointCarr (via de aangemaakte opdracht;
zie Opdrachten sectie op de PointCarr webpagina). Gebruik een PDF creator (bijv.,
CutePDF, pdf995, . . . ) om vanuit DrRacket de code naar een PDF document te exporteren. Zorg dat het verslag (exclusief broncode) niet meer dan 10 paginas beslaat. De
inhoudstafel van de code bevat op zijn minst de ADTs. Van de code geef je, naast een
makkelijk te lezen PDF-versie, ook een uitvoerbare versie af in een ZIP-archief.
De verslagen worden in principe in het Nederlands geschreven. Het is mogelijk om
de verslagen in het Engels te schrijven mits toelating van de docent. Een aantal concrete voorbeelden van coderapporten van vorige jaren zullen beschikbaar gesteld
worden op Pointcarr, en zullen besproken worden bij de projectvoorstelling.

4 Tijdens het project

Zodra je voorstudie klaar is kan je beginnen aan de implementatie van je ideen,
meerbepaald je ADTs. Begin met de uitwerking van de basis ADTs (implementeren

en testen) en bouw dan verder met de grotere ADTs.

Enkele tips:
Werk regelmatig: beter iedere week een paar uur dan alles in de laatste week
voor de deadline.
Gebruik het tijdschema uit je voorstudie als leidraad. Onthoud welke fases
van je project over/onderschat werden: je zal die verschillen moeten verantwoorden in je rapport. Hou hiervoor een logboek bij dat je later kan gebruiken
bij het maken van dit rapport.
Werk incrementeel: probeer altijd een werkende versie te hebben (hoe simplistisch ook), die je dan beetje bij beetje uitbreidt tot een complexere versie.
Test de aangepaste en toegevoegde componenten, evenals het geheel, na elke
uitbreiding. Schrijf op een systematische manier testcode, die je dan herbruikt
telkens je aanpassingen en/of uitbreidingen maakt.
Maak backups. Zorg ervoor dat je altijd een draaiende oude versie hebt (zie
ook vorige tip over incrementeel werken).
Gebruik ADTs! Implementeer je componenten m.b.v. ADTs uit de voorstudie. Begin met de eenvoudigste; test deze eerst afzonderlijk en gebruik deze
dan om andere, meer complexe ADTs op te bouwen. Je zal misschien nieuwe
componenten ontdekken of gebruik willen maken van hulp ADTs die je gezien hebt in de cursus Algoritmen en Datastructuren". (bijv., stacks, heaps,
bomen . . . ). Dat mag, maar steeds je bronnen vermelden natuurlijk!
Documenteer je broncode zorgvuldig. Het is belangrijk om vooral de interfaces van je ADTs duidelijk en systematisch te documenteren. Een andere
belangrijke vorm van documentatie is een duidelijke naamgeving van je variabelen, procedures, enz.
Praat met mensen (collega-studenten, assistenten) over je problemen. Let wel
dat je niet expliciet mag samenwerken. Deel geen code met je medestudenten!

5 Projectverdedigingen
Elke projectverdediging bestaat uit een korte demonstratie van de status van je project gevolgd door een discussie over je aanpak. Waar moet je opletten:
Er wordt op de verdediging een computer beschikbaar gesteld met de meest
recente versie van DrRacket. Je mag uiteraard ook je eigen laptop meebrengen.
Zorg er voor dat je een uitvoerbare versie van je programma bij hebt op een
USB-stick (zelfs al neem je je laptop mee). Zorg er ook voor dat, indien de
stick onverhoopt zou falen, je programma te downloaden is van een website.

Controleer of het volledige programma op deze gegevensdragers staat; d.w.z.

ook gebruikte initialisatie-bestanden, startup-bestande, bibliotheken,. . . Test
je code eerst op een andere machine voor je naar de verdediging komt.
Demonstreer stap voor stap de gehaalde doelstellingen aan de hand van een
goed voorbereid scenario. Het helpt om de stappen van dit scenario uit te
schrijven op papier. Probeer langdradige invoer te vermijden. Je kan bijv. invoer opslaan in een bestand waaruit je copy-paste.
Het is een verdediging: denk na over mogelijke kritiek en probeer ze op voorhand te ontkrachten. Verkoop je werk op een serieuze manier: schets de goede
kanten, maar ook de slechte.

6 Kwaliteitsvereisten
De algemene programmeerstijl is uitermate belangrijk en moet aan een aantal kwaliteitseisen voldoen. In deze sectie vind je een opsomming van een aantal concrete
kwaliteitseisen die je zeker dient te volgen!
Gebruik in je code nergens car en cdr, tenzij in de definitie van een ADT. Elk
jaar opnieuw krijgen we code binnen die vol staat met het gebruik van car en
cdr (en al hun varianten: cadr, caadr, cdar, ...). Dit is bijna steeds te wijten
aan het onvolledig begrijpen van waarom en hoe men abstracties gebruikt. De
enige plaats waar car en cdr mogen voorkomen in je code is in de definitie
van een ADT, niet in het gebruik ervan. Beschouw het volgende voorbeeld
waarin uitgelegd wordt hoe je op een correct manier abstraheert. Je wil een
punt voorstellen in een 3-dimensionale ruimte, en kiest een lijst om dit voor
te stellen:

(define (make-point x y z)
(cons x (cons y (cons z ()))))
Ergens in de code wordt dan bijvoorbeeld het volgende gedaan:

...

(if (= (car point) 1)

(display "x coordinaat is 1")
(display "x coordinaat is niet 1")) ...

Het probleem hier is dat jij als programmeur weet dat een punt wordt voorgesteld als een lijst van 3 elementen, en dat het eerste element de x-cordinaat
is. Je gebruikt dus je kennis van hoe punten worden voorgesteld midden in
je code. Het spreekt vanzelf dat dit het moeilijk maakt de voorstelling van
punten aan te passen, gezien je dan ook alle plaatsen in de code waar je van
deze kennis bent uitgegaan moet zoeken en wijzigen. Dit los je natuurlijk op
door abstracties te maken die het gebruik en manipulatie van een concept in
je code afschermt van de interne representatie van dat concept.

10

 Indien je in je code 2 of meer functies opmerkt die identiek zijn, op enkele details na, maak dan een algemenere functie. Maak eventueel gebruik van hogere
orde abstracties. In projecten komen we regelmatig het zogenaamde knipen-plak-hergebruik tegen. Knip-en-plak-hergebruik is een verbloemde term
voor codeduplicatie, en moet ten allen prijze vermeden worden.
Gebruik duidelijke naamgevingen in je code, die de bedoeling van de variabele
of functie ook voor anderen duidelijk maakt. Wees je er steeds van bewust dat
anderen je code zullen lezen, en variabelen met namen als i, tijdelijk, foo,
temp, bla, aux, parameter, flcntr enzovoorts de leesbaarheid van je code
allerminst bevorderen. Zelfs al gebruik je gauw even een variabele om te debuggen en ben je van plan om die variabele later terug weg te doen, dan nog
geef je die best een zinvolle naam. De beroemde opkuisfase komt er toch
bijna nooit, waardoor je code dan alsnog volstaat met betekenisloze variabelenamen.
Wees ook consistent in je naamgeving. Gebruik steeds dezelfde taal om je parameters/functies te benoemen: gebruik dus bijvoorbeeld altijd Nederlands,
of Engels, geen mengelmoes van de twee. Gebruik ook steeds dezelfde regels voor naamgeving: met of zonder koppeltekens, grote letters in een functienaam bij het begin van ieder nieuw woord, enz. Je kan voor verschillende
soorten functies, variabelen en dergelijke natuurlijk andere naamgevingen gebruiken, bijvoorbeeld interne variabelen van ADTs met kleine letters en globale variabelen in hoofdletters, zolang je dit maar consistent doet en je je aan
je eigen regels houdt. Beschrijf eventueel deze regels in je rapport.
Zorg dat er nergens in je code vastgebakken waarden voorkomen. Vastgebakken getallen komen meestal voor als boven- of ondergrenzen (bijvoorbeeld
het maximum aantal spelers bij een bordspel), aantallen voor iets (bijvoorbeeld het aantal agents dat in een systeem actief is) enzovoorts. Je kan dit
simpelweg vermijden door de hard gecodeerde waarden als constanten te definiren. Zorg er wel voor dat je code nergens steunt op een specifieke waarde
van een constante (je mag natuurlijk wel constanten gebruiken). Als je bijvoorbeeld een bordspel implementeert, en je wil (initieel) maximum 6 spelers
ondersteunen, zorg er dan voor dat je in je code er nergens vanuitgaat dat er
maar 6 spelers zullen zijn (bijv. door ergens expliciet 6 vectoren, 1 per speler,
aan te maken om bepaalde zaken bij te houden). Dit verhindert aanpasbaarheid.
Vermijd het gebruik globale variabelen. In het algemeen maken globale variabelen je code onduidelijk en onleesbaar. Het gebruik van globale variabelen
midden in je code zorgt er bovendien voor dat je code niet te hergebruiken
valt. Als je toch een globale variabele gebruikt in een functie, dan is het een
goed idee deze mee te geven als parameter. Zo steunt de betreffende functie
niet op het bestaan van deze globale, en kan ze aldus hergebruikt worden.
Hou je procedures kort. Procedures die in hun geheel op het scherm passen zijn
makkelijker te begrijpen. Op papier zouden procedures van een A4 lang uitzon-

11

derlijk moeten zijn, langer is zeker uit den boze. Te lange procedures maken je
code onleesbaar, en wijzen bijna steeds op het feit dat je niet genoeg geabstraheerd hebt. De informele richtlijn die je kan hanteren is dat een procedure die
niet op n A4 blad past echt wel te lang is.
Bij hergebruikte code dient steeds verwezen te worden naar de bron. Het is toegelaten, en wordt zelfs aangemoedigd, om code van anderen te hergebruiken, tenzij het in de opgave expliciet anders vermeld staat. We hebben het
hier uiteraard niet over het kopiren van collega-studenten die dezelfde projectopgave hebben als jij (voor alle duidelijkheid, dit is niet toegelaten), doch
wel over het gebruiken van bijvoorbeeld een standaardimplementatie van een
sorteeralgoritme of iets dergelijks. Je kan enkel open source code hergebruiken of code die komt uit de cursus van een bepaald vak. Het verschil tussen
hergebruiken van zulke code en stelen van code, is natuurlijk de bronvermelding. Bij ieder stuk hergebruikte code dien je te vermelden waar de code vandaan komt, zodat het duidelijk is dat je deze code niet zelf geschreven hebt.
Documenteer je code zodat ook anderen deze kunnen begrijpen. Niet gedocumenteerde code is per definitie slechte code. Hoe goed je je abstracties ook
maakt, hoe duidelijk je je naamgeving ook kiest, hoe proper je codeconventies ook zijn, je code zal steeds behoefte hebben aan duidelijke en consistente
documentatie als je wil dat derden je code op een vrij comfortabele manier
kunnen volgen.
Documenteer dus iedere niet triviale procedure/functie en ADT. Beschrijf wat
de procedure doet, en eventueel hoe dit gebeurt als dit niet meteen duidelijk
zou zijn. Geef duidelijk aan wat de argumenten zijn, en wat de output van de
procedure is.

7 Hints en tips
Tot slot nog enkele tips:
Leg een eigen deadline vast die bijv. een week of twee voor de echte deadline
ligt. Zo zorg je ervoor dat je project zeker op tijd af is, en dat je nog tijd genoeg
hebt om een goed verslag te schrijven.
Loop af en toe bij de begeleidende assistenten of bij InfoGroep langs om over
je project te praten. Zo vermijd je dat op de projectverdediging blijkt dat je het
verkeerd hebt aangepakt.
Begin te coderen zodra de voorstudie afgegeven is, anders zal je later te veel
werk hebben.
Een deel van de opdracht bestaat uit het weergeven van het resultaat van het
project (bijv., het speelbord bij een bordspel). Je zal dus eveneens ADTs moeten voorzien om te tekenen op het scherm. Opgelet: het is niet omdat iets er

12

mooi uit ziet op het scherm, of gewoon werkt, dat we tevreden zijn. Ook hier
moet er met herbruikbare en uitbreidbare ADTs gewerkt worden.
Er worden veel punten gezet op het ontwerp en het gebruik van ADTs. Een
project zonder ADTs of met slechte ADTs is per definitie een slecht project.
Druk de listings van je code af, zoals ze in de editor van je programmeeromgeving voorkomen. Bijgewerkte listings maken het veel moeilijker om de samenhang van de verschillende delen te begrijpen en geven een ongeloofwaardige indruk. Voorzie regelnummers en paginanummers zodat je een goede
inhoudstabel kan maken van je code.
Laat geen debugging code in de broncode staan. Het maakt ze onleesbaar.
Lees je verslag na! Verslagen met een hele berg schrijffouten worden niet geduld.

Referenties
[DOO en E. Mathijs, 2009] Dienst
OnderwijsOndersteuning
en
Erik
Mathijs (2009). Schrijfstijl wetenschappelijke tekst. [on line]; Beschikbaar
op
http://www.biw.kuleuven.be/doo/info_medewerkers/docs/
wetschrijven/Verslag.pdf [datum van opzoeking: 22/10/2012]

13