Tag documentatie
Altijd up to date documentatie met maximaal descriptieve tests
Door extra aandacht te besteden aan de scope en leesbaarheid van je tests, kun je deze transformeren van eenvoudig validatiemechanisme naar gezaghebbende bron van informatie voor ontwikkelaars. Met maximaal descriptieve tests is je documentatie altijd up to date.
Waar doe je het voor?
Een luie programmeur grijpt alles aan om zijn eigen werk makkelijker te maken (met uitzondering van het besparen op kwaliteit - daar is een andere term voor: een slechte programmeur). En makkelijker maken betekent meestal: automatiseren. Want waarom zou je zelf het werk doen, als een machine het ook voor je kan doen?
Tijdreis
Ik vroeg mijn collega’s: “Wat doet dit ding precies?” - waarop ze prompt de code tevoorschijn haalden en me stap voor stap door het importproces loodsten. Het was alsof ik terug werd geslingerd naar het begin van mijn ontwikkelcarrière, toen we met z’n allen een twaalf jaar oude legacy applicatie onderhielden die alleen te doorgronden was door nauwgezet de code te doorlopen. Wat blijkt: tijdreizen bestaat - je hoeft alleen maar bij een ander team te buurten.
Testen met productiedata
Laatst kwam ik een test tegen die checkte of een bepaald object 48 keer voorkwam in een lijst. Het was een hartstikke valide test, daar niet van. Maar hij riep wel de vraag op: waarom 48 keer?
Aantekeningen over requirements - deel 2
Het opstellen van de juiste requirements is één van de moeilijkste onderdelen van softwareontwikkeling. In een eerdere blog beschreef ik de eerste acht lessen die Karl Wiegers of dit onderwerp formuleerde in Software Development Pearls. In deze blog volgen de tweede acht.
Aantekeningen over requirements - deel 1
Het moeilijkste onderdeel van softwareontwikkelen is niet het juist bouwen, maar het juiste bouwen. Vaak zwoegen programmeurs dagenlang op hun code en worstelen testers zich door het resultaat heen, om er pas helemaal op het eind van de ontwikkelcyclus achter te komen dat er iets is gebouwd waar eindgebruikers niet helemaal (of: helemaal niet!) op zaten te wachten. Het scheppen van een juist beeld van wat er gemaakt moet worden is misschien wel de belangrijkste stap in het ontwikkelen van software - en niet zelden de minst ontwikkelde.
Waarom documentatie belangrijk is
Er is behoefte aan documentatie. Documentatie voorziet nieuwe ontwikkelaars van een kader, een context waarbinnen ze de code kunnen begrijpen. Het alternatief is: hen zelf een context laten ontwikkelen op basis van de code. Dat is niet alleen veel tijdrovender, het brengt ook het risico met zich mee dat ze zich een onjuist begrip van de code vormen.
Tests zijn specs
Kleine (of liever: te kleine) tests geven weinig informatie over de werking van het systeem. Ze verlangen van de lezer om op de hoogte te zijn van implementatiedetails, en verliezen zo het grote geheel uit het zicht. Voor grotere unittests gaat die beperking niet op. Zulke tests doen geen aannames over de interne werking van het systeem. Ze beschrijven slechts de buitenkant ervan: wat de gebruiker - hoe we die dan ook mogen definiëren - invoert en wat deze terugkrijgt. Het gevolg daarvan is dat je tests leesbaar worden voor niet-ontwikkelaars.
Over de volgorde van je unit tests
Maakt het uit in welke volgorde je unit tests staan? - Nee. Tests slechts een middel om de werking van het systeem te valideren. Het maakt niet uit in welke volgorde de tests worden afgetrapt, als ze maar allemaal slagen. (Of liever: als ze maar op het juiste moment falen.) Dat is een mogelijk antwoord. - In een praatje van Kevlin Henney vond ik een ander antwoord.
Betere documentatie door PR-templates
Elk pull request biedt een gelegenheid om documentatie te schrijven. Toen ik dat punt een tijd geleden inbracht tijdens het tweewekelijkse Alignment-overleg van mijn team, viel mij tot mijn verbazing een hoop instemmend geknik ten deel. Hoe plezierig dat ook was, eerlijk gezegd verwachtte ik niet per se dat mijn pleidooi veel navolg zou vinden. Programmeurs en documentatie is en blijft nu eenmaal een moeilijk huwelijk. Maar mijn team verraste me positief.