9 retningslinjer for å lage uttrykksfulle navn

Navngiving er subjektiv og situasjonsavhengig, det er en kunst, og som med det meste av kunst, oppdager vi mønstre. Jeg har lært mye gjennom lesing av andres kode. I denne artikkelen har jeg samlet 9 retningslinjer som jeg ønsket andre hadde fulgt når jeg leste deres kode.

Når en programvareingeniør åpner en klasse, bør hun vite, basert på navnene, klassens ansvar. Ja, jeg vet at navngiving bare er en del av hjulet, fysiske og logiske strukturer spiller også en betydelig rolle i forståelsen av koden, det gjør også kompleksitet. I denne artikkelen fokuserer jeg bare på navngiving fordi jeg mener det har størst innvirkning på forståelsen av koden.

Ikke inkluder type med mindre det avklarer intensjonen

En type kan være alt fra en programmeringstype (string, int, decimal) til en gruppering av ansvar (Util, Helper, Validator, Event, osv.). Ofte er det en klassifisering som ikke uttrykker intensjon.

La oss se på et eksempel: Navnet StringHelper uttrykker ikke mye. En string er en systemtype, og Helper er vag, StringHelper snakker mer om “hvordan” enn intensjonen. Hvis vi i stedet endrer navnet til DisplayNameFormatter, får vi et klarere bilde av intensjonen. DisplayName er veldig spesifikt, og Formatter uttrykker resultat. Formatter kan eller kan ikke være en type, men det spiller ingen rolle, fordi det uttrykker intensjon.

Det er alltid unntak; for eksempel i ASP.Net MVC må kontrollere ende på “Controller” eller applikasjonen fungerer ikke. Ved å bruke paradigmer som Domain Driven Design (DDD), har navn som “Services,” “Repository,” “ValueType” og “Model” betydning i DDD og uttrykker ansvar.

For eksempel antyder UserRepository at brukerdata hentes og lagres i et datalager.

Unngå metaforer

Metaforer er kulturelle, og ingeniører fra andre kulturer forstår kanskje ikke intensjonen.

Vanlige metaforer i USA:

• Beating a dead horse
• Chicken or the egg
• Elephant in the room

Vanlige metaforer i New Zealand:

• Spit the dummy
• Knackered
• Hard yakka

Bruk verb

Steve Yegge skrev et (veldig langt) blogginnlegg om å bruke verb fremfor substantiver.

Hans poeng er å bruke verb, applikasjoner består av substantiver, men substantiver gjør ikke ting. Systemer er ubrukelige med bare substantiver, i stedet uttrykk handling i navn på metoder.

For eksempel uttrykker UserAuthentication*(substantiv).AuthenticateUser(handling/verb)* handlingen med å verifisere en brukers legitimasjon.

Vær beskrivende

Vær beskrivende, jo mer detalj, jo bedre — uttrykk ansvaret i navnet.

Spør deg selv, hva er den ene tingen denne klassen eller funksjonen gjør godt?

Hvis du har vanskeligheter med å finne et navn, kan klassen eller funksjonen ha mer enn ett ansvar og dermed bryte Single Responsibility Principle.

Ikke stol på kommentarer for intensjon

Kommentarer er en fin måte å gi tilleggskontekst til koden, men stol ikke på kommentarer. Navnene på klasser og metoder bør stå på egne ben.

I Refactoring: Improving the Design of Existing Code av Martin Fowler, Kent Beck, John Brant, William Opdyke og Don Roberts:

… kommentarer brukes ofte som deodorant. Det er overraskende hvor ofte du ser tett kommentert kode og legger merke til at kommentarene er der fordi koden er dårlig.

Et annet flott sitat fra forfatterne av “In Refactoring”:

Når du føler behov for å skrive en kommentar, prøv først å refaktorere koden slik at enhver kommentar blir unødvendig. Side 88

Mange ganger når koden refaktoreres og innkapsles i en metode, vil du finne andre steder hvor det er mulig å utnytte den nye metoden, steder du aldri forventet å bruke den nye metoden.

Noen ganger når du kaller en metode, trenger forbrukeren å vite noe spesielt om metoden, hvis det særegne er en del av navnet, trenger forbrukeren ikke å gjennomgå kildekoden.

Her er et eksempel på å inkorporere en kommentar i et navn.

Med kommentarer:

// without tracking
var user = GetUserByUserId(userId);

Refaktorert for å inkludere kommentaren i metodenavn:

var userWithOutTracking = GetUserByUserIdWithoutTracking(userId);

Andre ingeniører vet nå at denne metoden ikke har sporing før de trenger å enten lese kildekoden eller finne kommentaren.

Kommentarer bør være din siste forsvarslinje når det er mulig, stol på andre måter å uttrykke intensjon på, inkludert å bruke fysisk og logisk struktur og navn for å formidle intensjon.

Avhold deg fra å bruke navn med tvetydig betydning

Unngå navn med tvetydig betydning. Betydningen av tvetydige navn endres fra prosjekt til prosjekt, noe som gjør det vanskeligere for en ny ingeniør å forstå intensjonen.

Her er en liste over vanlige tvetydige navn:

• Helper
• Input
• Item
• Logic
• Manager
• Minder
• Moniker
• Nanny
• Overseer
• Processor
• Shepherd
• Supervisor
• Thingy
• Utility
• Widget

Bruk samme språk som forretningsdomenet

Bruk samme terminologi i koden som i forretningsdomenet. Dette gjør det mulig for ingeniører og fageksperter (SME) å enkelt kommunisere ideer fordi de deler samme ordforråd. Når det ikke er et delt ordforråd, skjer oversettelse som uunngåelig fører til misforståelser.

I ett prosjekt jeg arbeidet med, startet virksomheten med “Pupil” og byttet deretter til “Student.” Programvareingeniørene oppdaterte aldri programvaren for å reflektere endringen i terminologi. Når nye ingeniører kom til prosjektet, trodde de fleste at Pupil og Student var forskjellige konsepter.

Bruk industristandardspråk

Når det er mulig, bruk terminologi som har betydning på tvers av programvareindustrien.

De fleste programvareingeniører, når de ser noe navngitt “factory,” tenker umiddelbart på factory-mønsteret.

Bruk av eksisterende applikasjonsparadigmer som “Clean Architecture” og “Domain Driven Design” letter idedealing og skaper et felles språk for ingeniører å kommunisere ideer blant seg selv.

Den verste mulige navngivingen er å ta over industriomfattende terminologi og gi den en annen betydning.

Når du navngir boolske verdier…

Boolske navn bør alltid være et svar på et spørsmål med verdien enten sann eller usann.

For eksempel isUserAuthenticated, svaret er enten ja (true) eller nei (false)

Bruk ord som:

• Has
• Does
• Is
• Can

Unngå negerte navn, for eksempel:

Et negert variabelnavn:

var IsNotDeleted = true; // this is confusing

if(!IsNotDeleted) { // it gets even more confusing when the value is negated
  //Do magic
}

Uten negert variabelnavn:

var IsDeleted = true; // this is confusing

if(!IsDeleted) { 
  //Do magic
}

Til slutt

Å velge uttrykksfulle navn er avgjørende for å kommunisere intensjon, design og domenekunnskap til neste ingeniør. Ofte arbeider vi med kode for å fikse defekter eller inkorporere nye funksjoner, og vi kompilerer kontinuerlig kode i hodet vårt for å forstå hvordan det fungerer. Navngiving gir oss hint om hva den forrige ingeniøren tenkte, uten denne kommunikasjonen mellom tidligere og fremtidige ingeniører hemmer vi oss selv i veksten av applikasjonen. Potensielt fordømmer prosjektet til fiasko.