De TOPBEV-Richtlijn
Het goed toepassen van coding guidelines blijft moeilijk. Veel van deze richtlijnen zijn omvangrijke documenten, maar de programmeur die ze moet toepassen, kent de te gebruiken code standaarden niet uit het hoofd of vindt ze te moeilijk. Ergo: het is tijd voor een coding guideline van één A4-tje.
Inleiding
Coding guidelines of codeerstandaarden: ik heb er ondertussen wel een aantal gezien. De kleinste is 26 pagina's, de meeste zijn een veelvoud daarvan. Bij code reviews blijkt vaak dat collega-programmeurs een dergelijk intern gebruikte standaard "wel eens heeft gelezen", maar goed toepassen blijkt moeilijk. Er is altijd wel een excuus om deze niet toe te hoeven passen. De belangrijkste redenen zijn: men kent de te gebruiken code standaarden niet uit het hoofd of men vindt ze te moeilijk.
Hoewel ik in dit artikel uitga van Visual Studio en C#, lijkt mij deze richtlijn ook van toepassing op andere programmeertalen.
TOPBEV
De coding guideline die ik altijd gebruik heet: TOPBEV. Dit is een acroniem dat ik als ezelsbruggetje gebruik als ik mijn hersenspinsels aan de code editor toevertrouw. Dit is makkelijker te onthouden dan een document van meer dan 26 pagina's. TOPBEV staat voor Transparant, Onderhoudbaar, Performant, Betrouwbaar, Elegant (of Eenvoudig) en Veilig. Bij iedere class die ik toevoeg aan mijn project, iedere methode die ik verzin of elke regel code die ik schrijf, vraag ik mij af: is dit transparant, onderhoudbaar, performant, betrouwbaar, elegant en veilig?
Laat ik uitleggen wat ik met deze begrippen bedoel.
Transparantie
Transparantie heeft te maken met het snel krijgen van overzicht en inzicht in de code. Als je snel inzicht wil hebben, dan zul je aannames moeten doen (iets wat ik niet graag doe). Essentieel hierbij is naamgeving.
Ik stel mij hierbij altijd de vragen: bevat de code een heldere structuur en een duidelijke, intuïtieve naamgeving? Als een andere collega deze code onder handen krijgt, kan hij dan veilige aannames doen ten aanzien van de code? Vindt hij dan snel zijn weg in de code?
Minstens net zo belangrijk als naamgeving is documentatie en commentaar. Maak in .NET gebruik van de XML-documentation tags (http://msdn2.microsoft.com/en-us/library/b2s063f7.aspx). Becommentarieer geen triviale zaken maar vooral de niet evidente stukken code.
Onderhoudbaarheid
In de life-cycle van een applicatie wordt tussen 60% en 80% van de totale kosten besteed aan beheer en onderhoud. Dat betekent dat jouw code vooral onderhoudbaar moet zijn, want daarin is veel financiële performance (= winst) te halen. Onderhoudbaarheid heeft o.a. te maken met consequent zijn in je code, maar ook met de opzet en inrichting van je Visual Studio solution (bestanden en directories). Ik ben meer dan eens Visual Studio-solutions tegengekomen met meer dan 30 projecten erin. Dit is niet onderhoudbaar (en ook niet transparant overigens).
Codeduplicatie (ofwel code knippen en plakken) zondigt ook tegen deze regel. Wanneer dezelfde code twee of meer keer in één class voorkomt, dan moet hiervoor een aparte methode komen. Als eenzelfde code twee of meer keer voorkomt in verschillende classes, dan moet hiervoor een aparte (static/shared?) methode in een aparte of andere class komen. Ook methodes die langer zijn dan 50 regels zijn kandidaat voor refactoring.
De vraag die ik mij hierbij stel, is: kunnen andere mensen mijn code lezen en aanpassingen in maken zonder dat er onvoorziene "issues" optreden?
Performantie
Performantie is de heilige graal van veel ontwikkelaars. Waarom? Omdat performance één van de weinige kwaliteitsaspecten is die kwantitatief eenvoudig kan worden gemeten. Naast bugs in applicaties is gebrek aan performance de meest gehoorde klacht van gebruikers. Maar applicatie performance is een draak met vele koppen. En jij hebt meestal maar invloed op slechts één van deze: de code. Op zaken als hardware, infrastructuur, architectuur en bijvoorbeeld de aanwezigheid van indexen op tabellen heb jij als programmeur niet altijd invloed. Maar zaken waarop jij wel invloed hebt, moet je dan ook goed gebruiken.
Vermijd extra roundtrips naar de backend systemen. Gebruik de juiste objecten (bijv. StringBuilder i.p.v. string bij het aan elkaar plakken van tekst). Breek tijdig uit je loops en maak deze niet langer dan nodig. Dit is natuurlijk allemaal evident. De grootste moeilijkheid van deze richtlijn is vooral: rechtvaardigen de offers die ik breng in mijn code om de gewenste performance te halen, het corrumperen van de regels ten aanzien van transparantie en onderhoudbaarheid.
Stel je zelf bij het wegen van performance de vraag: doet de code zijn werk binnen de gestelde tijdslimiet en binnen de verantwoordelijkheid van die code?
Betrouwbaarheid
Betrouwbaarheid beschouwt de code vanuit gebruikersperspectief. Stel jezelf de vraag: doet de code wat de gebruikers ervan verwachten? Kunnen zij erop vertrouwen dat het doet wat het moet doen? Dit kan te maken hebben met User Interface design: staan de OK- en Annuleer-knoppen rechts onderin het scherm? Gedragen knoppen, tekstboxen en andere UI-controls zich zoals een gebruiker dit verwacht? Pas op: neem jezelf niet als uitgangspunt. Jij bent namelijk geen "gewone" gebruiker.
Dit punt heeft ook te maken met performance en multi-threading. Als een gebruiker lang moet wachten totdat een proces is afgerond, dan wordt hij zenuwachtig. Heeft de gebruiker dan de mogelijkheid om een actie af te breken? Lees: voer langlopende processen uit op een andere thread.
Elegantie
Elegantie is de essentie van de wetenschappelijke nalatenschap van Edsger Wiebe Dijkstra (http://www.cs.utexas.edu/users/EWD/) waarbij elegantie, kort door de bocht, wordt vertaald als het kiezen van de minst complexe oplossing voor een (programmeer)probleem. Dit punt heeft voor mij vooral te maken met "de kunst van het programmeren". En bij kunst gaat het toch vooral om de schoonheid.
Art has to be forgotten, Beauty must be realized (Mondriaan)
Dit is ook de E van eenvoud. Ik vraag mij, als het om elegantie gaat, bij een class of methode dan ook altijd af: is dit de meest mooie, efficiënte en vooral eenvoudigste implementatie van een oplossing?
Veiligheid
Veiligheid heeft uiteraard te maken met requirements en hangt af van organisatorische procedures en beschikbare infrastructuur, maar dit zijn zaken waarop programmeurs niet altijd invloed hebben. Ik heb het hier over de veiligheid waarvoor de programmeur verantwoordelijk is. Dit heeft niet alleen te maken met encryptie of de validatie van wachtwoorden maar ook met foutafhandeling.
Als het om veiligheid gaat, zul je veel moeten ‘dialogeren’ met infra-mensen, architecten en opdrachtgevers. Ik gebruik expres het woord dialogeren i.p.v. communiceren: bij het voeren van een dialoog ben je afhankelijk van een antwoord.
Over foutafhandeling kan ik nog de nodige pagina’s vullen, maar neem voor wat betreft foutafhandeling in ieder geval de belangrijkste regel in acht: handle only those exceptions that you can handle gracefully.
Voor veiligheid vraag ik mij af: compromitteert de code niet de omgeving waarin het wordt uitgevoerd (memory leaks e.a.) of de identiteit waaronder het wordt uitgevoerd. Is de code te vertrouwen?
TOPBEV in de praktijk
Het nadeel van TOPBEV als coding guideline is, dat deze nogal aan interpretatie onderhevig kan zijn. Ook is het toepassen van TOPBEV als richtlijn erg afhankelijk van kennis en ervaring. Maar coding guidelines zijn per definitie wat de naam al aangeeft: het zijn richtlijnen. Het doel van coding guidelines is de uitwisselbaarheid van (de te lezen) code tussen programmeurs bevorderen, fouten te verminderen en zo kwaliteit te verbeteren. Maar kwaliteit is eveneens een subjectief begrip. Gebruik daarom TOPBEV als een ezelsbruggetje om je kwaliteitsbewustzijn te schragen.
Daarnaast ben ik een groot voorstander van het doen van code reviews. Probeer deze dan ook binnen je project te initiëren en/of binnen jouw organisatie te formaliseren. Het doen van code reviews levert een aantal voordelen op:
- fouten kunnen in een vroeger stadium worden ontdekt;
- jouw interpretatie van een requirement wordt door een ander gevalideerd;
- je kunt veel van een ander leren;
- een ander kan veel van jou leren;
- als jij er niet bent dan begrijpt een ander ook jouw code – dan kan je tenminste rustig op vakantie en je mobiel en laptop thuis laten.
Als je daarnaast nog behoefte hebt om de coding guidelines binnen jouw organisatie meer vorm te geven kijk dan in ieder geval naar:
Als tools zaken voor je kunnen oplossen, dan heeft dat natuurlijk de voorkeur. Static Code Analysis in Visual Studio kan je goed helpen bij het toepassen van coding guidelines. Mocht deze niet in jouw versie van Visual Studio zitten dan kan je altijd nog FxCop los downloaden en installeren
Persoonlijk ben ik wel gecharmeerd van de "IDesign C# Coding Standard, for development guidelines and best practices": http://www.idesign.net/. Het leuke is dat er een tool is die deze standaard kan valideren:
Conclusie
Als code voldoet aan (de eisen van):
- Transparantie
- Onderhoudbaarheid
- Performantie
- Betrouwbaarheid
- Elegantie (en Eenvoud)
- Veiligheid
... dan gaat de code er in kwaliteit op vooruit!
Als je deze zes woorden op een A4-tje afdrukt en er af en toe naar kijkt dan weet je: TOPBEV is een acroniem om nooit meer te vergeten.