Clean Code: Naamgeving

Welkom » Blog » PHP » Clean Code: Naamgeving

12/12/2020 | bitween | PHP

Hoe schrijf je clean code in de praktijk? Wat is er voor nodig om naar code te kijken en te zeggen: het is geweldig? In deze serie van artikelen geef ik je een aantal korte tips over het schrijven van clean code: de gouden standaard voor het ontwikkelen van software. In dit artikel: hoe geef je betekenisvolle namen aan de elementen van software?

Waarom?

There are only two hard things in Computer Science: cache invalidation and naming things.
Phil Karlton

Het geven van betekenisvolle namen is moeilijk. Wanneer ik terugkijk naar code die ik 6 maanden geleden geschreven heb, denk ik vaak: wat staat hier? Wat duidt een variabele met de naam ‘d’ aan? Geen idee! Om te snappen wat deze variabele voorstelt, moet ik eerst naar de context van de code kijken. Dat kost tijd en energie en dat is niet nodig. Daarom is het zo belangrijk om dingen een duidelijke naam te geven. Zo weet jij 6 maanden later ook nog wat je precies bedoelde met deze code.

Hoe?

Het is niet makkelijk om goede namen te geven aan dingen. Daarom geef ik hieronder een aantal concrete voorbeelden van correcte naamgeving. Ik denk dat het geven van juiste namen berust op: intentie, verschil en consitentie.

Intentie

Een naam van een variabele, class of functie moet 3 vragen beantwoorden:

Waarom bestaat het?
Wat doet het?
Hoe wordt het gebruikt?

Een voorbeeld hiervan zijn de volgende namen van variabelen:

<?php

// Waarom bestaat het: manier om aan te duiden hoeveel dagen er verstreken zijn.
int $elapsedTimeInDays = 5;

// Wat doet het: het geeft een naam aan een variabele waarde  die de afstand in kilometers aanduidt.
int $distanceInKilometers = 75;

// Hoe wordt het gebruikt: als een list (wat aanduidt dat het gebruikt kan worden in een loop).
List $listOfCustomers = new List();

Misleiding

Naamgeving moet niet misleidend zijn. Dat wil zeggen: de naam van een ding moet niet in conflict zijn met hetgene de naam daadwerkelijk representeert.

Een voorbeeld van een misleidende naam is het volgende:

<?php

// De naam is misleidend, aangezien dit geen List is, maar een Collection.
Collection $listOfAccounts;

Verschil

Verschillende dingen moeten verschillende namen hebben. Hieruit volgt ook dat dingen die hetzelfde aanduiden ook dezelfde naam moeten hebben. Zo ben je consistent in je naamgeving en dat is belangrijk.

Een voorbeeld van code waarbij de namen niet verschillend zijn, maar wel verschillende concepten aanduiden:

<?php

public function copyChars(array $a1): array {
    $a2 = [];
 
    for($i = 0;$i < count($a1); $i++) {
        $a2[$i] = $a1[$i];
    }  

    return $a2;
}

$a2 is hier een ander concept dan $a1. $a2 is namelijk de kopie van invoer-array $a1. Het is dus dezelfde (soort) naam voor een ander concept. De manier waarop deze code verbetert kan worden is het volgende:

<?php

public function copyChars(array $input): array {
    $copy = [];
 
    for($i = 0;$i < count($input); $i++) {
        $copy[$i] = $input[$i];
    }  

    return $copy;
}

In de bovenstaande code is er een duidelijk verschil tussen de invoer en de uitvoer. Wanneer je 6 maanden naar bovenstaande code kijkt, snap je dat de $input daadwerkelijk iets anders is dan de $copy.

Consistentie

Wanneer je consistent bent in de naamgeving, kun je door alleen al naar de naam van een ding te kijken, weten wat het doet en voorstelt. Stel dat je altijd ‘get’ gebruikt als prefix van een methode die iets ophaalt uit een API. Dat is consistent. Als je dat doet, weet je dat iets wat geprefixed is met ‘get’ iets ophaalt uit een API. Je hoeft hiervoor dan niet meer in de code zelf te kijken wat er gebeurd. Een dat scheelt tijd en energie.

Een voorbeeldje:

<?php

class ProductApi {
    public function get(): array;
}

class ShopApi {
    public function get(): array;
}

class ProductCategoryApi {
    // Doordat we consistent zijn in de naamgeving, weten we dat deze methode iets ophaalt uit een API.
    public function get(): array;
}

Conclusie

Hierboven heb ik een aantal voorbeelden gegeven van wat ik ‘clean code’ noem. Ik ben specifiek ingegaan op het geven van namen. Als je dieper op dit onderwerp in wilt gaan, raad ik je het boek ‘Clean Code’ aan. De volgende keer ga ik specifiek in op het schrijven van clean functies. Tot de volgende keer!

JarnoVogelzang