Tag documentatie
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.
Pull requests als documentatie
Hoe vaak denk je na over de titel en omschrijving van je pull request? Als je een beetje op mij lijkt, dan is het antwoord: veel te weinig. Het goede nieuws is: je hoeft er niet over na te denken, want dat hebben de vriendelijke ontwikkelaars van Google al voor je gedaan. Onlangs las ik hun Code Review Developer Guide door, en vond daar een schat aan informatie.
Tests als documentatie
Tests zijn een vorm van documentatie. Ze leggen vast hoe een deel van je codebase zich hoort te gedragen. Maar ook: hoe je dat deel van de codebase gebruikt - wat je nodig hebt om het system under test te instantiëren, het gedrag van z’n methods etc.. Wie de tests leest, weet hoe de code gebruikt dient te worden. - Althans, dat is de ideale wereld.
Collegiale documentatie
Ik ken geen enkele ontwikkelaar die het leuk vindt om documentatie te schrijven - ik ook niet - en dat is omdat goede documentatie schrijven moeilijk is. Het is moeilijk, omdat je je vanuit een positie van iemand die snapt hoe iets werkt, je in moet leven in iemand die dat begrip nog niet heeft. Mijn belofte “even” documentatie te schrijven werd daarom al gauw “een uur” documentatie schrijven. Maar het resultaat is volgens mij wel de moeite waard, dus laten we er even (…een uur?) naar kijken.
De noodzaak van refactoren
Ons team heeft een stakeholder wiens gezicht vertrekt, elke keer als we tijdens een Sprint Review aangeven tijd te hebben gestoken in het refactoren van onze applicatie. In zijn beleving is refactoren een verspilling van je tijd. Als we meer tijd hadden genomen om de wensen van onze gebruikers grondig te analyseren, redeneert hij, dan had zo’n dure, inefficiënte refactorslag kunnen worden voorkomen. Als ik iemand zo hoor redeneren, dan vertrekt míjn gezicht.
Goede code documenteert zichzelf (niet)
Uit de code valt niet af te leiden wat de specificaties zouden moeten zijn. Om met David Hume (1711-1776) te spreken: een ought valt niet af te leiden uit een is. Wie zegt dat goede code zichzelf documenteert, maakt zich schuldig aan de naturalistische dwaling. En toch zit er een kern van waarheid in het idee dat goede code zichzelf documenteert.
Tijd om te ontwerpen
Ik heb jarenlang als ontwikkelaar code kunnen kloppen zonder ooit maar één stroomdiagram te hoeven bekijken. Een grappig gegeven, want één van de eerste dingen die ik moest doen toen ik solliciteerde naar een traineeship als back end developer, was een cognitietaak waarbij ik steeds complexere stroomdiagrammen voor mijn neus kreeg. En om de indruk te wekken dat software ontwikkelen méér is dan alleen naar een scherm staren, moest ik dat doen in een ruimte behangen met foto’s van mensen die lachend naar whiteboards staan te wijzen.
"Niet zo bijzonder"
Onze stagiaire heeft onlangs een volledige Sprint besteed aan het op orde krijgen van haar documentatie. Tijdens de Sprint Review karakteriseerde ze die twee weken werk als “niet zo bijzonder”. Ik kwam tegen die woorden in het verweer.