Ja, dit citaat wordt in development te vaak gebruikt. Het leent zich goed voor veel grappen, maar onderstreept ook het belang van het benoemen van “dingen”. Dat is op zichzelf een ironisch voorbeeld van het onderliggende vraagstuk: “dingen” is geen goede naam.
Gelukkig zijn er regels, richtlijnen en best practices ontstaan, en ondergetekende gelooft dat je die tijdens development makkelijk kunt leren, toepassen en volgen. “Dingen” goed benoemen is een onderdeel van goede code schrijven, en mag niet worden afgedaan omdat het geen functioneel onderdeel van die code is. Laten we een paar voorbeelden bekijken.
Conventies en consistentie
Wat je ook doet, wees consistent en houd je aan conventies. Die kunnen verschillende vormen hebben.
Gebruik snakeCase voor variabelen in JavaScript. Gebruik namen met een hoofdletter voor types in TypeScript. Houd je constanten helemaal UPPERCASE. POST betekent aanmaken, PUT betekent bijwerken. Er zijn veel industriestandaarden die je hoort te volgen. Als je ze zonder goede reden niet volgt, ben je in feite het wiel opnieuw aan het uitvinden. Een wiel dat duizenden programmeurs weten te gebruiken, terwijl alleen jij je specifieke implementatie waarschijnlijk kent, en die anderen makkelijk op het verkeerde been zet.
Standaarden
Controleer of er een standaard is voor wat je doet. Is het een API? Misschien volg je dan de OpenAPI Specification. Voor CSS kun je kijken naar BEM. Voor Javascript kun je EsLint en Prettier gebruiken. Schrijf semantische html om toegankelijkheid te verbeteren.
Soms kunnen standaarden ook functionele impact hebben. Vue raadt in zijn style guide aan om componenten namen te geven met twee of meer woorden. Daar zit een praktische reden achter: componenten worden naast HTML-tags ingevoegd als <ExampleComponent />. Een component “article” noemen kan problemen geven, omdat HTML al een <article>-tag heeft. Wat doe je als je niets beters kunt bedenken? Noem hem misschien “TheArticle”, of nog beter “AnArticle”, als tegenhanger van “singleton”-componenten zoals “TheNavbar”.
Types
Regels volgen bij het benoemen van een specifiek type kan je code leesbaarder maken. Als je betalingen in een array zet, hoort die waarschijnlijk meervoudig te zijn: “payments”. Als je die “payment” zou noemen, moet je waarschijnlijk al snel ongemakkelijke keuzes maken, zoals hoe je de elementen noemt in een iterator als payment.map(singlePayment => […]). Vergelijkbare best practices bestaan voor andere types:
- Arrays: gebruik meervoudige namen
- Booleans: laat het type zien door ze te laten beginnen met is, has, can
- Numbers: voeg specificiteit toe met: base, maximum, total, minimum, enzovoort.
- Class methods en properties kunnen een afgeleide semantische context hebben, namelijk de naam van de class zelf. Dat betekent dat je binnen een class Potato misschien geen method getPotato wilt hebben. Je wilt hem misschien “get” noemen. Die method wordt in elk geval op de class aangeroepen, dus Potato.getPotato() is misschien wat dubbelop, terwijl Potato.get() makkelijker leest en direct ter zake komt.
Een jargon of woordenlijst ontwikkelen
Een grote hulp bij naamgeving kan komen uit het jargon van het vakgebied van je klanten. Werk je met financiële instellingen, dan hebben je klanten hoogstwaarschijnlijk een zeer gevestigd en door de praktijk gehard jargon dat je vraagstukken oplost en tegelijk de communicatie met hen makkelijker maakt. Je hoeft niet eens volledig te begrijpen wat de term voor de klanten betekent. Jij brengt als developer andere vaardigheden mee dan je klant die investment manager is. Ik begrijp nog steeds niet helemaal wat een “ledger” is, maar ik weet wel wat het betekent in onze codebase, voor mijn team en met onze klant.
Een vast jargon consistent gebruiken is misschien niet makkelijk, zeker vroeg in een project. Het opschrijven in de vorm van een woordenlijst kan het gebruik ervan versterken en dubbelzinnigheid voorkomen. Een woordenlijst voor elk project lijkt in het begin misschien niet nodig, maar het is een vorm van documentatie die jou, je team en klanten later helpt. Verschillende projecten kunnen verschillende woordenlijsten hebben. “Order” in een e-commerceapplicatie betekent iets, maar op een religieus platform iets heel anders. Afhankelijk van dag en tijd doet “bar” mij denken aan bier of grafieken. Het is belangrijk om woordenlijsten per project of domein te scheiden.
Specificiteit
Mijn docent simultaan tolken op de universiteit werd behoorlijk boos als we generieke woorden gebruikten terwijl we het juiste woord kenden. “A man walking on the street” kost nogal wat tijd om te zeggen, en hoewel het hetzelfde kan betekenen als “pedestrian”, is dat vaak niet zo. Het lopen is wat belangrijk is. De man blijft een voetganger als hij over een plein loopt. Gender is waarschijnlijk niet belangrijk, dus “person” zou een betere keuze zijn dan man, en “pedestrian” vangt dat ook af.
Hetzelfde geldt voor development. “User” is overal aanwezig omdat het zo generiek is. “Customer” is misschien beter voor e-commerce. Op een leenplatform kunnen je users verder worden opgesplitst in “borrowers”, “lenders”, “loanees” en “applicants”. Dat geeft precisie. Je bakent je code in feite af om beter te begrijpen naar welke “users” je precies verwijst.
Een ander voorbeeld dat vaak terugkomt in development is bedragen, soms values of numbers genoemd.
Als je beseft dat het “amount” moet worden opgesplitst in een bedrag voor en na belasting, maak dan niet alleen “amount” en “amountWithTax”. Verander “amount” naar “amountWithoutTax”. Nu je meer informatie tot je beschikking hebt, kun je nieuwe betekenis geven aan de oorspronkelijke variabele “amount”. Als je verder wilt gaan, kun je kijken hoe al deze bedragen in de financiële wereld worden genoemd, wat kan leiden tot “amountGross” en “amountNet”. Of het leidt tot verwarring, omdat je niet echt een FinTech-app schrijft, en je teamleden en/of toekomstige jij niet vertrouwd zijn met de verschillen tussen gross en net, maar wel weten wat belastingen zijn.
Maar wees voorzichtig. Het is niet zoals een uur achter elkaar code schrijven, die dan draaien en herstellen wat je verkeerd deed. Verkeerde variabelenamen gooien geen exceptions. Stop alle betekenis die je kunt in één variabelenaam, zonder dat die verkeerd wordt.
De voordelen van goede naamgeving
Een goede, consistente naamgevingsstrategie helpt je om op koers te blijven met je project. Het werkt als herinnering aan wat je eigenlijk doet in termen van business logic. Het laat je iets langer nadenken voordat je code gaat schrijven, waarom je die schrijft en wat je probeert te bereiken. Het kan communicatie makkelijker maken, omdat je team consistent naar dezelfde dingen verwijst met dezelfde naam. Het kan zoeken in je codebase makkelijker maken, net als refactoring. Het kan je tijd besparen bij het controleren welk type een variabele heeft en je code vloeiender en leesbaarder maken. Het kan je helpen de behoeften van je klant beter te begrijpen en je daarop te richten. Het kan helpen bij het inwerken van nieuwe developers door breed geaccepteerde standaarden te gebruiken die ze kennen en begrijpen.
En dit alles kost weinig meer dan nadenken over hoe het “ding” moet heten voordat je het schrijft. En dat is het moeilijke deel, kijk maar naar de titel van dit artikel.