Ik vind het schrijven van software een prachtig onderdeel van mijn baan, omdat bijna alles mogelijk is. Er wordt een idee bedacht om te bouwen, voor dat idee wordt een tech stack gekozen, en vervolgens wordt er vanuit niets iets gemaakt. Natuurlijk worden er tools, frameworks, en programmeertalen gebruikt, maar het echte begin is een lege editor zonder enige code. Deze vrijheid zorgt er alleen ook voor dat iedereen een eigen mening kan hebben over... nou ja, alles. Een style guide kan zorgen om een deel van de ontwikkeling binnen bepaalde grenzen te houden. Gelukkig kunnen die grenzen per groep afgesproken worden en is er geen gouden oplossing die voor iedereen werkt, dus we zijn niet alle vrijheid kwijt. Maar wat is een style guide precies? Waarom zou een style guide gebruikt moeten worden? Dat ga ik in deze blogpost toelichten.
Een style guide is een verzameling conventies die voorschrijven hoe code geschreven moet worden voor een specifiek project. Denk hierbij aan de formatting van de code zoals de indentatie; wordt deze met spaties of met tabs gedaan, en hoeveel precies. Of welke manier gebruikt moet worden voor het plaatsen van haakjes. Een limiet zetten voor het aantal karakters per regel is ook een veelgebruikte style guide regel. Wist je dat er vroeger zelfs een harde limiet van 80 karakters per regel was? Dit kwam door de tijd waar men nog met punch cards programmeerde - de punch cards van IBM hadden een maximum van 80 karakters per regel.
Er zijn veel onderdelen van programmeren die beschreven kunnen worden in een style guide. Grote tech bedrijven hebben hun style guides online staan, maar ook programmeertalen hebben soms een standaard style guide. Google en Airbnb hebben bijvoorbeeld style guides online staan die veel gebruikt en erg bekend zijn. Van de programmeertalen is een bekende style guide die van Python, bekend onder de naam PEP-8 (Python Enhancement Proposal 8). Nieuwe projecten gebruiken deze style guides vaak als basis, echter, omdat ze zo veelomvattend zijn, passen de projecten aan wat zij nodig vinden. Een uitgebreider overzicht van style guides vind je hier: https://github.com/Kristories/awesome-guidelines.
Om een beeld te krijgen van wat er beschreven kan worden in een style guide, heb ik hier een aantal voorbeelden uit de Google Java style guide.
Er worden zes onderdelen beschreven:
Mijn voorstel om een style guide te gebruiken, krijgt regelmatig weerstand van collega's. Ik hoor vaak "als het maar te lezen is toch?", of "zolang het werkt maakt het niet uit hoe de code eruit ziet". Ik denk dat het volgen van een style guide belangrijk is, ongeacht de werking van de code.
Laat mij je meenemen in een kort verhaal. Het moment is aangebroken dat je als software engineer begint in een nieuwe codebase. Je bent er vol op gebrand om zo snel mogelijk te begrijpen wat er gebeurt in de code. Je download het project, begint met het lezen van de code, en… je hebt geen idee wat er gebeurt. Er is code die buiten het scherm valt, de indentatie varieert in lengte, soms zijn er witregels en soms totaal niet. Het gebruiken van haakjes gebeurt inconsistent, en bij elk stuk nieuwe code wat je tegenkomt, heb je geen idee wat je moet verwachten qua styling of logica. Na een paar uur is er meer tijd op gegaan aan begrijpen wat je hebt gelezen dan begrijpen wat de code doet. Zonde van de tijd, en frustrerend omdat je zo had gehoopt op een eenvoudige en snelle start.
Het bovenstaande verhaal is een perfect voorbeeld waarom ik een style guide belangrijk vind. Stel dat de code geschreven zou zijn volgens een style guide. In dat geval zou er consistentie zijn in de formatting van de code, de toegepaste logica, en eventueel ook in de opzet van de bestanden. Hierdoor wordt de codebase voorspelbaar waardoor hij makkelijk te navigeren is, en de code leest makkelijker omdat alles in dezelfde opzet is geschreven. Ook hoeft er geen discussie meer te zijn over welke stijl er toegepast wordt - dit is al besloten en ligt vastgelegd in de style guide. Daardoor kan er gefocust worden op het bouwen van nieuwe functionaliteit in plaats van discussies over de stijl te voeren.
Ik heb een minimum aan drie style guide regels die ik overal toegepast zou willen zien.
Als eerste, de indentatie. Wordt er met vier spaties gewerkt, of misschien met twee? Als tweede moet er een karakterlimiet per regel zijn, waarbij mijn voorkeur ligt op 120 karakters per regel. Als derde, welke methode voor haakjes (indentation style) wordt er gebruikt? Er zijn veel verschillende methoden hiervan, maar mijn favoriet is Kernighan & Ritchie stijl, ook wel bekend als K&R. Het openende haakje aan het einde van de eerste regel code, het sluitende haakje op een nieuwe regel:
while (x == y) {
something();
}De tegenhanger van K&R is vaak de stijl van Eric Allman, bekend onder de “Allman” stijl.
Daarbij krijgt elk haakje zijn eigen regel:
while (x == y)
{
something();
}Style guides worden al heel lang toegepast in andere industrieën. De wetenschap hanteert bijvoorbeeld style guides voor het noteren van referenties, zoals de Modern Language Association en de American Psychological Association guides. Voor marketing is een goede style guide zelfs bijna essentieel voor merkherkenning. Denk maar aan de witte oortjes van Apple; voordat Apple begon met witte oortjes waren ze allemaal zwart. Ook de wereld van boeken gebruikt style guides. Deze zijn zelfs zo bekend dat iedereen weet hoe een boek is opgebouwd: een bepaald aantal hoofdstukken die bestaan uit meerdere paragrafen, met op elke pagina een vast aantal karakters per regel. Stel je voor dat je een boek zou kopen waarbij elke regel ergens anders op de pagina begint en eindigt.
Persoonlijk vergelijk ik het schrijven van code met het schrijven van een boek. In beide gevallen wordt er tekst geschreven. In beide gevallen moet het format voorspelbaar zijn zodat het begrijpbaar is en het fijn leest. De consistentie van de styling en de voorspelbaarheid van wat er gaat komen, zorgen ervoor dat de focus ligt op content. Bij een boek is dat het verhaal, en bij een code is dat de logica die geïmplementeerd is.
Hopelijk is de belangrijkheid van een style guide ondertussen duidelijk, en is nu de vraag hoe deze toegepast kan worden. Globaal zijn er twee manieren:
Het documenteren van een style guide is de oude manier waarop een style guide werd gehandhaafd. Software engineers moeten hierbij elkaar controleren op het naleven van de style guide, en het document moet aangepast worden als er veranderingen zijn. Het nadeel van deze aanpak is dat een document vrij eenvoudig genegeerd kan worden. Ook kunnen engineers het niet eens zijn met de style guide en iets anders doen dan wat is voorgeschreven.
De aanpak van het forceren van een style guide is tegenwoordig een populaire. Linters zoals Prettier komen met een geopinieerde, vooraf bepaalde set regels die worden afgedwongen door middel van het scannen van de code. Als ergens de code niet voldoet aan de regels, kan dit direct aangegeven worden. Op deze manier kunnen software engineers de style guide altijd toepassen via een linter check. De linter kan geconfigureerd worden om een error of een warning te geven. Hierdoor kan een team zelf bepalen of ze de build compleet willen stoppen, of alleen een waarschuwing willen. Nog beter, de linter kan in elke stap van het development proces worden meegenomen:
Zelf ben ik een groot voorstander van style guides. Het zorgt voor consistentie, voorspelbaarheid, en leesbaarheid van de code. Waar je ook komt in de code, de stijl is herkenbaar waardoor de focus op logica kan blijven liggen. Daar komt bij dat je weet dat je collega's op dezelfde manier de code zullen schrijven. Via linters zijn style guides eenvoudig toe te passen zodat er geen tijd verloren gaat. Uiteindelijk zal iedereen baat hebben bij het toepassen van een style guide. En nee, een style guide hoeft niet heel uitgebreid en complex te zijn. Mij maak je allang blij met drie regels; welke methode voor haakjes gebruiken wij, wat is de karakterlimiet per regel, en hoeveel spaties indentatie gebruiken wij?