Inleiding:
Voor dit Building Block ga ik gebruik maken van 2 CLE projecten. Voor de uitdagingen “Verzorging code” en “Overdracht” zal ik gebruik maken van bewijsmateriaal uit CLE2, hierbij moesten we een reserveringssysteem maken voor een zelf uitgekozen opdrachtgever. Voor de uitdaging “Versiebeheer” zal ik het project uit CLE4 gebruiken, hierbij moesten we een arcadegame maken. Ik heb als hulpmiddel bij dit building block alle kennisclips gekeken met betrekking tot dit building block.
Verzorging code
Functies en kritieke onderdelen in code (onderdelen die niet in één oogopslag te verklaren zijn) zijn voorzien van comments. Logische structuur in componenten van je project. Variabelen en functies hebben beschrijvende namen. Je bent je bewust van code conventies van de programmeertaal waarin je werkt.
Programmeren is niet mijn sterkste kant, dus het is behalve voor anderen ook belangrijk voor mezelf dat mijn code duidelijk is d.m.v. logische structuur (maps), comments en beschrijvende namen.
Ik ben begonnen met de logische structuur, hiermee bedoel ik dat de files van mijn project verdeeld zijn in maps en deze logische namen hebben. Belangrijk hierbij is dat het in het Engels is en de namen ook logisch zijn voor andere programmeurs (stel zij gaan aan jouw project werken).
Reservationsystem is de naam van het gehele project en hierin zitten alle andere maps en files. Daaronder heb ik nog 3 maps aangemaakt. Clients bevat alle files die te maken hebben met het maken van de afspraak bij de garage. Hierbij horen ook de files die foutmeldingen geven wanneer een veld niet is ingevuld (errors.php) en de file die de connectie legt met de server, zodat de afspraak opgeslagen wordt in de database.
De user map bevat alle files die te maken hebben met het inloggen, uitloggen, aanmaken van een gebruiker (in dit geval een werknemer van de garage) en het inzien van de afspraken (en deze kunnen wijzigen en verwijderen) door de gebruiker. Hierbij hoort ook nog de config.php en database.php file, die weer de connectie en communicatie met de database vastleggen.
Als laatst is er ook nog een vendor map, deze is echter niet zo belangrijk, want ik moet voor het back-end building block een library toevoegen (faker library heb ik gebruikt), dus ik vond het handig om alle files hiervan ook in een map te stoppen.
De 2 css files heb ik niet in mappen gedaan, want deze zijn onderdeel van (bijna) elke file, dus deze heb ik “algemeen” gehouden door ze niet in een map te doen.
Daarna heb ik mijn code verzorgd door te commenten. Dit zorgt ervoor dat ik zelf weet wat ik met de code bedoel, en zo ook anderen mijn code sneller snappen. Ik heb de comments ook in het Engels gedaan, omdat dit dan ook voor internationale programmeurs makkelijker te lezen is. Hieronder een aantal screenshots van mijn code waarin gecomment is:
Dit komt uit de admin.php file, hierin comment ik dat de wachtwoord die de gebruiker op dat moment aanmaakt gevalideerd moet worden (2 keer zelfs), daarna wordt er gecheckt of er errors zijn voordat het in de database wordt gezet.
Hier comment ik dat er een afspraak verwijderd kan worden (deze wordt dan ook gelijk uit de database gehaald), ook de connectie met de database wordt afgesloten en na het verwijderen van de afspraak wordt je terugverwezen naar table.php, oftewel het overzicht van alle afspraken.
Sommige comments spreken voor zich, zoals een session starten, toch vind ik het voor mezelf fijn om deze comment erbij te zetten (als volledigheid). Bij if-statements zet ik er altijd graag bij wat er wordt gecontroleerd (in dit geval het checken of de gebruiker al ingelogd is en of de gebruikersnaam en wachtwoord velden leeg zijn).
Als laatst laat ik hier zien dat ik de variabelen aanmaak en hoe ik de afspraak maak. Hierbij moeten de “input values” ingevuld worden.
Je ziet ook in de foto hierboven (en de 1e en 3e foto van mijn code) dat ik gebruik maak van underscores (_), zo wordt het duidelijk dat er een voornaam, achternaam en telefoonnummer in dit geval verwacht wordt van de klant om een afspraak te maken. Zo gebruik ik beschrijvende namen voor variabelen.
Versiebeheer
Je kan met een versiebeheersysteem samen aan een product werken, waarbij ieders inbreng gelijkwaardig is. Je kunt uitleggen hoe versiebeheer werkt, en waarom dit geschikter is voor samenwerken aan code dan bijv. Dropbox. Commits zijn klein en beschrijf je ook kort en bondig.
Met mijn projectgroepje in CLE4 hebben we samengewerkt in Github. Ik, Inci en Jasper maakten gebruik van de Github Desktop app en Eva maakte gebruik van Gitkraken (vond ze fijner). Eerst moest er een repository aangemaakt worden, we hadden besloten deze “Horns&Hooves2” te noemen (de naam vanwege het feit dat we eenhoorns hadden gekregen als X-Factor en de nummer 2 omdat de eerste repository niet helemaal gelukt was, dus we het opnieuw moesten doen). Eva had dit uiteindelijk gedaan, maar ze deelde haar scherm op teams tijdens het proces en hebben met z’n allen meegekeken en geholpen hierbij. Daarna hebben we hierin verschillende branches aangemaakt. Je hebt de master branch, hierin komt uiteindelijk alle code, je kan dit ook wel de “default branch” noemen. Daarnaast hebben we een develop branch, hier kom ik zo op terug. Eva uit mijn groepje kwam met het idee om voor elk teamlid een aparte branch aan te maken. Dit omdat we dan onze eigen code waaraan we dan gewerkt hadden, in onze eigen branch konden doen. Ik heb bijvoorbeeld aan het creditsscherm gewerkt. Toen deze af was, heb ik deze gepusht naar mijn eigen branch (noomi). Wat we dan als groepje hadden afgesproken was dat wanneer de code 100% klopte van iemand, deze gepusht werd naar de develop branch. In de develop branch kon alleen maar goeie code staan, want vanuit deze branch kon je mergen. Mergen houdt in dat je jouw eigen branch samenvoegt met de betreffende branch (in dit geval de develop branch). Zo kon iedereen in het groepje up-to-date blijven van de juiste code en kon de rest van mijn groepje bijvoorbeeld mijn creditsscherm ook in hun code krijgen, maar kon ik ook bijvoorbeeld het tutorialscherm van Inci in mijn code krijgen door mijn branch te mergen met de develop branch (stap daarvoor was dat inci haar code vanuit haar eigen branch naar de develop branch zou pushen). Met deze link kom je terecht in ons Github project voor CLE4.
In de screenshot hierboven zie je dat de commits kort worden beschreven, bij bijvoorbeeld het creditsscherm staat: “creditspage finished”, dit is kort en bondig, iedereen weet dat de pagina af is en dat is met 2 woorden omschreven.
Ook kreeg ik tijdens het project last van een “merge conflict”. Dit houdt in dat de branches die je wil mergen tegenstrijdige commits bevatten. Dit kreeg ik toen ik mijn branch wilde mergen met de branch van Eva (zie foto hieronder). Ik heb dit opgelost door te kijken bij welke file(s) het merge conflict lag. Dat bleek bij docs/main.js te liggen (dat geeft Github mooi aan links van het scherm). Je drukt daarna op de rechtermuisknop en dan klik je op “discard changes”. Zo verdwijnt de merge conflict en kun je de gewenste branches wel met elkaar mergen.
Met goed versiebeheer zorg je ervoor dat voor iedereen duidelijk is welk document – en daarmee welke informatie – het meest recent en actueel is. Zodat je daar als organisatie de beslissingen op kunt baseren. Je beschikt over deze voordelen:
- samen tegelijkertijd aan één document werken.
- tijdwinst: de juiste informatie is sneller te vinden.
- altijd de meest recente versie beschikbaar.
- werken in oude of verkeerde versies is verleden tijd.
- informatie is – ook achteraf – juist op te vatten.
- zie je precies wie welke wijzigingen wanneer heeft gedaan.
- is er minder opslagruimte nodig omdat een document maar op één plek staat.
- is de juiste informatie gemakkelijker te delen.
(bron: https://digioffice.nl/blog/wat-is-versiebeheer/ )
Overdracht
Je bent in staat acceptatiecriteria (definition of done, specificaties) zodanig op te stellen dat het product te bouwen is door iemand anders zonder verder overleg. Je bent in staat om een klantgerichte gebruikershandleiding op te leveren.
Hieronder zijn de user stories weergegeven met de acceptatiecriteria erbij, dit heb ik van te voren overlegd met mijn opdrachtgever:
Definition of done is wel anders dan de acceptatiecriteria, bij definition of done moet het duidelijk worden wat er nodig is om het doel te behalen, deze verandert dan ook niet vaak. Bij acceptatiecriteria staat het centraal om aan de eisen van een klant te voldoen, deze kunnen nog weleens veranderen.
Ik heb hieronder m.b.v. Trello een definition of done overzicht gemaakt:
Ik heb de definition of done hierin verwerkt door aan de belangrijkste en “grotere” taken, checklists toe te voegen. Zo heb ik zelf een goed overzicht van welke onderdelen er nodig zijn totdat de taak is afgerond. Hieronder geef ik het voorbeeld van de reserveringspagina en de loginpagina:
Als laatst heb ik hieronder nog een handleiding gemaakt:
Als je op de link klikt (dus niet op download), komt de handleiding als het goed is tevoorschijn in een lightbox. Anders kun je het nog altijd downloaden.