Joel on Software

Joel on Software   Joel over Software

 

Andere "Joel on Software" artikelen in het Nederlands

Andere "Joel on Software" artikels in het Engels

Email de auteur (uitsluitend in het Engels)

 

Pijnloze Functionele Specificaties - Deel 1: Waarom al die moeite?


Door Joel Spolsky
Vertaald door Jurgen Bettonviel
Geredigeerd door Bernard Vander Beken
2 oktober 2000

Op het moment dat De Joel Test het licht zag werd het schrijven van specificaties door de lezers gezien als zowat de zuurste appel om doorheen te bijten. Het lijkt dat het schrijven van specs iets is als flossen: iedereen weet dat ze moeten geschreven worden, maar niemand doet het.

Waarom schrijven mensen geen specs? Mensen beweren tijd te besparen door het schrijven van een specificatie over te slaan. Ze doen net alsof het schrijven van een specificatie een luxe is die alleen NASA space shuttle ingenieurs of mensen die voor grote gevestigde verzekeringsmaatschappijen werken zich kunnen veroorloven. Nonsens. Ten eerste is het nalaten een specificatie te schrijven het allergrootste onnodige risico in een software project. Dat is net zo stom als jezelf laten droppen midden in de Sahara met alleen wat kleren in je rugzak, in de hoop het te overleven. Programmeurs en software engineers die in de code duiken zonder vooraf een spec te schrijven denken vaak dat ze "coole" vanuit de heup schietende revolverhelden zijn. Maar dat zijn ze niet! Zij zijn verschrikkelijk contraproductief. Ze schrijven slechte code, produceren rammelende software en ze zijn een bedreiging voor hun projecten omdat ze onnodig grote risico's nemen.

Ik geloof dat elk niet-triviaal project (meer dan 1 week code-kloppen of meer dan 1 programmeur) zonder spec altijd uitloopt en kwalitatief mindere code oplevert. En wel hierom:

De belangrijkste functie van een spec is het ontwerpen van het programma. Zelfs als je de enige bent die aan code werkt en de spec uitsluitend voor jezelf bedoeld is, dwing je jezelf middels het schrijven van de spec -- beschrijven van de werking van het programma in detail -- om in feite het programma te designen.

Laten we eens twee imaginaire programmeurs opzoeken bij twee bedrijven. Bij Hasty Bananas Software werkt Speedy. Speedy schrijft nooit specificaties. "Specs? Wij hebben geen duffe specs nodig!" Mr. Rogers daarentegen, die werkt bij The Well-Tempered Software Company, weigert ook maar één regel code te schrijven totdat de spec compleet is. Dit zijn slechts twee van mijn vele imaginaire vrienden.

Speedy en Mr. Rogers hebben een ding gemeen: Beide zijn ze verantwoordelijk voor de "backwards"-compatibiliteit van versie 2.0 van hun producten.

Speedy besluit dat het schrijven van een converter die simpelweg versie 1.0 bestanden converteert naar versie 2.0 bestanden de beste manier is om backwards-compatibiliteit te verwezenlijken. Ze begint gelijk de code te rammen. Typen, typen en nog eens typen, klikje hier klikje daar. Harde schijven draaien op volle toeren, stof waait op en twee weken later heeft ze een redelijke converter. Maar Speedy's klanten zijn niet tevreden. Speedy's code dwingt ze namelijk om iedereen in het bedrijf in één keer te upgraden naar de nieuwe versie. Speedy's grootste klant, Nanner Splits Unlimited, weigert om de nieuwe software te kopen. Nanner Splits wil weten of versie 2.0 nog met versie 1.0 bestanden kan werken zonder conversie naar versie 2.0 bestanden. Speedy besluit daarop een backwards converter te schrijven en deze in de "save" functie op te roepen. Eigenlijk is het een beetje een puinhoop: het lijkt namelijk te werken tot je een feature gebruikt van versie 2.0 en de file opslaat in versie 1.0 formaat. Pas dan komt de mededeling dat de feature die je een half uur geleden hebt toegepast niet werkt in het oude formaat. Gevolg, nog eens twee weken implementatie en het werkt nog niet echt mooi. Totaal verstreken tijd is dan 4 weken.

Welnu, Mr. Rogers van Well-Tempered Software ("WellTemperSoft" voor intimi) is een van die haast overgeorganiseerde kereltjes die weigeren code te schrijven voordat ze in het bezit zijn van een spec. In 20 minuten heeft hij dezelfde backwards-compatibiliteit functionaliteit als volgt beschreven:

  • Bestanden die gemaakt zijn met een oude versie worden bij openenen geconverteerd naar het nieuwe formaat.

Deze specificatie wordt getoond aan de klant en die zegt: "Wacht eens even!  We gaan niet iedereen met de nieuwe versie laten werken!" Daarop gaat Mr. Rogers nog even nadenken en past de specificatie als volgt aan:

  • Bestanden die gemaakt zijn met een oude versie worden bij openenen in het geheugen geconverteerd naar het nieuwe formaat. Als het bestand vervolgens weer wordt opgeslagen heeft de gebruiker een optie het bestand terug te converteren naar het oude formaat.

Opnieuw zijn er twintig minuten verstreken.

De baas van Mr. Rogers, een object freak, kijkt er eens naar en vindt dat er iets aan schort. Hij stelt een andere architectuur voor:

  • De code wordt ingedeeld in twee interfaces: V1 en V2. V1 bevat alle versie 1 features. V2, die versie 1 features erft van V1, voegt alle nieuwe features toe. Op deze manier kan V1::Save zorg dragen voor de backwards compatibliteit en V2::Save kan de nieuwe features opslaan. Als je een V1 bestand opent en probeert V2 functionaliteit toe te passen, kan het programma je meteen waarschuwen. Je hebt dan de keuze tussen converteren naar versie 2 of de nieuwe functionaliteit buiten beschouwing laten.

Nog eens 20 minuten.

Mr. Rogers is er maar knorrig onder: Deze implementatie komen hem op 3 i.p.v. de door hem aanvankelijk geschatte 2 weken te staan. Het lost echter wel elegant alle problemen op die bij de klant kunnen optreden. En zo geschiedde!

Drie weken en een uur had Mr. Rogers nodig. Vier weken voor Speedy, maar met slechte code.

De moraal van het verhaal is dat alles te bewijzen valt met een goed geconstrueerd voorbeeld. Oeps, dat is niet wat ik wilde zeggen. De moraal van het verhaal is dat als je je product in menselijke taal ontwerpt, het maar enkele minuten duurt om na te denken over verbeteringen, te reviseren en het ontwerp te verbeteren. Niemand zal een traan laten als een paragraaf in een tekstverwerker wordt verwijderd. Maar als je je design daarentegen maakt in een programmeertaal, duurt het weken om designs incrementeel te verbeteren. Sterker nog, een programmeur die zojuist 2 weken heeft zitten coderen raakt gehecht aan die "prachtig geconstrueerde" code, ongeacht de slechte kwaliteit van die code. Speedy's baas of klant kunnen zeggen wat ze willen, niets kan haar overtuigen haar code weg te gooien, zelfs niet als die niet het beste ontwerp voorstelt. Dit resulteert vervolgens in een eindproduct dat een compromis is tussen het initiële slechte design en het ideale design. Het was het "beste design dat we konden krijgen, simpelweg omdat we al die code al geschreven hadden en we die niet zomaar weg wilden gooien." Lang niet zo goed dus als het "beste design dat we konden krijgen, punt!"

Dat is dus mega-reden nummer één om een specificatie te schrijven. Mega reden nummer twee is tijd besparen op communicatie. Als je een specificatie schrijft, hoef je maar  één keer de werking van het programma te communiceren. Iedereen in het team kan daarna gewoon de specificatie lezen.
De kwaliteitsmensen lezen het om te weten te komen hoe het programma zou moeten werken zodat ze weten wat ze moeten testen. Marketingmensen lezen het zodat zij vage "white papers" kunnen schrijven waarmee ze producten die nog moeten gemaakt worden aanprijzen op de website. De business development mensen misinterpreteren het document om hun vreemde fantasieën aan te jagen omtrent hoe het product wratten heelt; maar zij halen investeerders binnen, dus dat is OK. Ontwikkelaars lezen het om te weten welke code ze moeten schrijven. Klanten lezen het om er zeker van te zijn dat de ontwikkelaars een product implementeren waar ze voor hebben betaald. Technische schrijvers lezen het en schrijven een mooie handleiding (die overigens toch verloren gaat of wordt weggegooid, maar dat is een ander verhaal). Managers lezen het zodat zij net kunnen doen of ze weten wat er allemaal gebeurt in de development teams tijdens management vergaderingen. Etc., etc.

Als je geen specificatie hebt, gebeurt deze communicatie alsnog, omdat dat nu eenmaal moet, maar het gebeurt ad hoc . De kwaliteitsmensen schieten maar wat in het wilde weg op het programma en als ze iets vreemds vinden gaan ze de programmeur(s) weer lastig vallen en stellen ze nog een stomme vraag over wat het programma nou eigenlijk moet doen. Dit ruïneert niet alleen de productiviteit van programmeurs, maar programmeurs hebben ook nog eens de neiging te antwoorden op een manier die overeenkomt met wat ze hebben gecodeerd, i.p.v. met het "juiste antwoord". Dus de kwaliteitsmensen testen het programma tegen het programma in plaats van tegen het ontwerp. Dat laatste zou, ahum, een beetje nuttiger zijn.

Wat er met de arme technische schrijvers gebeurt als er geen specificatie voorhanden is, is het grappigst (een beetje zielig eigenlijk). Technische schrijvers ontberen vaak de autoriteit om programmeurs te mogen onderbreken. Bij de meeste bedrijven gaan programmeurs die worden gestoord door technische schrijvers naar hun manager en klagen daar dat ze toch echt niet kunnen werken door die [krachtterm gewist] schrijvers en of ze die aub weg willen houden. De managers gaan op hun beurt de technische schrijvers verbieden om de kostbare tijd van programmeurs in beslag te nemen in een poging de productiviteit te vergroten. Deze bedrijven haal je er zo uit, omdat de help-files en handleidingen een gebruiker niet meer informatie geven dan die op het beeldscherm kan vinden. Als je de volgende boodschap op het beeldscherm ziet:

  • Wilt u ondersteuning voor LRF-1914 inschakelen?

en je vervolgens op "Help" klikt, duikt er een tragikomisch help onderwerp op:

  • Hier kunt u kiezen uit LRF-1914 ondersteuning (standaard) of geen LRF-1914 ondersteuning. Indien u LRF-1914 ondersteuning wenst, kiest u "Ja" of drukt u op "J". Als u geen LRF-1914 wenst kiest u "Nee" of drukt u op "N".

Ahum, dank je. Het is hier nogal duidelijk dat de technische schrijver probeerde te verbergen dat hij niet wist wat LRF-1914 ondersteuning is. Hij kon het niet vragen aan de programmeurs omdat hij of (a) zich ervoor schaamde of (b) de programmeur in Hyderabad is en hijzelf in London of (c) hij door het management teruggefloten is omdat hij de programmeurs stoorde of ieder ander excuus dat te belachelijk is voor woorden, terwijl het ontbreken van een specificatie het echte excuus was.

De derde belangrijke mega-reden om een spec te schrijven  is dat het onmogelijk is om een planning te maken zonder een gedetailleerde specificatie. Het ontbreken van een planning is niet erg als het om je doctoraat gaat en je van plan bent om 14 jaar te gaan werken aan het ding, of als je als programmeur werkt aan de volgende Duke Nukem en een en ander pas wordt uitgebracht als we helemaal klaar zijn.  Maar in de realiteit van de hedendaagse software-handel, moet je weten hoe lang een en ander gaat duren, want het ontwikkelen van een product kost geld. Niemand koopt een spijkerbroek zonder te weten hoeveel hij kost; hoe kan een zichzelf respecterend bedrijf dan besluiten een product te maken zonder te weten hoe lang dat gaat duren en dus te weten hoeveel het gaat kosten? Meer over planning kun je lezen in  Pijnloze Software Planning.

Een ongelooflijk veelvoorkomende fout is een discussie die nooit afgesloten wordt over hoe iets moet worden gespecificeerd. Brian Valentine, hoofd ontwikkelaar voor Windows 2000, was beroemd vanwege zijn motto : "Beslissingen in 10 minuten of minder, of de volgende is gratis."

Veel te veel software-bedrijven debateren - meestal om politieke redenen - besluiteloos  over een specificatie. Dus werken de programmeurs alleen aan niet-controversiële stukken. Gaandeweg worden alle moeilijke beslissingen naar het einde uitgesteld. Deze projecten hebben de meeste kans om te falen. Als je een nieuw bedrijf opstart rond een nieuwe technologie en je komt erachter dat je bedrijf constitutioneel niet in staat is om beslissingen te maken, kun je net zo goed meteen sluiten en het geld terug sturen naar de investeerders. Je zult wellicht toch nooit met een afgewerkt stuk software voor de dag komen.

Het schrijven van een specificatie is een fantastisch middel om al die irritante grote en kleine design beslissingen vast te leggen die anders over het hoofd worden gezien. Zelfs kleine en "onbelangrijke" beslissingen kunnen zo worden vastgelegd. Stel dat je een website bouwt waarvoor gebruikers zich moeten aanmelden.  Iedereen is het er wellicht mee eens dat een gebruiker een vergeten wachtwoord via mail kan worden gestuurd. Mooi! Maar dat is niet genoeg om de code te kunnen schrijven. Je moet namelijk weten welke woorden er in die mail komen de staan. De meeste bedrijven laten teksten die aan klanten worden gepresenteerd niet schrijven door programmeurs (en meestal om de juiste redenen). Marketing- of PR-mensen moeten de tekst voor de email aanleveren. "Beste ukkel, hier is het wachtwoord dat je vergeten bent! Probeer in het vervolg niet zo vergeetachtig te zijn." Als je jezelf dwingt een goede en complete specificatie te schrijven (veel meer daarover later), dan komen deze zaken vanzelf naar boven en ga je ze of ophelderen (als de zaken nog niet duidelijk waren) of je gaat ze op z'n minst markeren met een grote rode vlag.

OK. We begrijpen elkaar nu. Specs zijn van fundamenteel belang. Ik verwacht dat de meeste mensen dit begrijpen en mijn gedachtenspinsels leren de lezer niets nieuws. Maar, waarom worden er dan geen specs geschreven? Niet om tijd te besparen, want dat doe je niet. Volgens mij weten de meeste programeurs dat. (In de meeste organisaties zijn de enige specificaties enkele A4-tjes die een programmeur snel in Notepad schreef nadat de code is geschreven en nadat hij feature X voor de 300ste keer besproken heeft met andere mensen.)

Volgens mij komt het doordat zoveel mensen niet graag schrijven. Staren naar een wit scherm is ongelooflijk frustrerend. Persoonlijk heb ik deze angst overwonnen door een cursus te volgen die mij dwong elke week een stuk te schrijven van 3 tot 5 A4-tjes. Schrijven is een spier. Hoe meer je schrijft, des te meer je zult kunnen schrijven. Als je een spec moet schrijven en het lukt niet, creëer een weblog, ga een cursus creatief schrijven volgen of schrijf gewoon een brief naar elke bekende of studiegenoot die je beledigd hebt de afgelopen 4 jaar. Alles wat je doet dat het schrijven van stukken tekst behelst verbetert je schrijfvaardigheid. Als je een software development manager bent en de mensen in je teams schrijven niet de specs die ze moeten schrijven, dan kun je ze best voor twee weken op een cursus creatief schrijven in de bergen sturen.

Als je nog nooit in een bedrijf hebt gewerkt dat gewoon is te werken met functionele specificaties dan is het waarschijnlijk dat je er nog nooit een gezien hebt. In het volgende deel van deze serie presenteer ik je een korte voorbeeld specificatie en zullen we het bovendien hebben over de voorwaarden voor een goede spec. Lees verder!



De originele versie van dit artikel verscheen in het Engels onder de naam Painless Functional Specifications  

Joel Spolsky is de oprichter van Fog Creek Software, een klein softwarebedrijf in New York. Hij studeerde af aan de Yale universiteit, en heeft als programmeur en manager gewerkt bij Microsoft, Viacom en Juno.


De inhoud van deze pagina's vertegenwoordigt de mening van één persoon.
Alle inhoud Copyright ©1999-2005 door Joel Spolsky. Alle rechten voorbehouden.

FogBUGZ | CityDesk | Fog Creek Software | Joel Spolsky