At sætte kommentarer i kode: det gode, det dårlige og det grimme.

Stop mig, hvis du har hørt denne før ...

"God kode er selvdokumenterende."

I 20+ år med at skrive kode for at leve, er dette den sætning, jeg har hørt mest.

Det er kliché.

Og som mange klichéer har den en sandhedskerne. Men denne sandhed er blevet så misbrugt, at de fleste mennesker, der udtaler sætningen, ikke aner, hvad det virkelig betyder.

Er det sandt? Ja .

Betyder det, at du aldrig skal kommentere din kode? Nej .

I denne artikel ser vi på det gode, det dårlige og det grimme, når det kommer til at kommentere din kode.

For det første er der virkelig to forskellige typer kodekommentarer. Jeg kalder dem dokumentationskommentarer og afklaringskommentarer .

Dokumentationskommentarer

Dokumentationskommentarer er beregnet til alle, der sandsynligvis vil forbruge din kildekode, men som sandsynligvis ikke læser igennem den. Hvis du bygger et bibliotek eller en ramme, som andre udviklere vil bruge, har du brug for en form for API-dokumentation.

Jo længere fjernet fra kildekoden din API-dokumentation er, desto mere sandsynligt er det, at det bliver forældet eller unøjagtigt over tid. En god strategi for at afbøde dette er at integrere dokumentationen direkte i koden og derefter bruge et værktøj til at udtrække den.

Her er et eksempel på en dokumentationskommentar fra et populært JavaScript-bibliotek kaldet Lodash.

Hvis du sammenligner disse kommentarer med deres online-dokumentation, kan du se, at det er et nøjagtigt match.

Hvis du skriver dokumentationskommentarer, skal du sikre dig, at de følger en ensartet standard, og at de let kan skelnes fra eventuelle inline-præciseringskommentarer, du muligvis også vil tilføje. Nogle populære og godt understøttede standarder og værktøjer inkluderer JSDoc til JavaScript, DocFx til dotNet og JavaDoc til Java.

Ulempen ved denne type kommentarer er, at de kan gøre din kode meget “støjende” og sværere at læse for alle, der er aktivt involveret i at vedligeholde den. Den gode nyhed er, at de fleste kodeeditorer understøtter "kodefoldning", hvilket giver os mulighed for at skjule kommentarerne, så vi kan fokusere på koden.

Afklaringskommentarer

Præciseringskommentarer er beregnet til alle (inklusive dit fremtidige selv), der muligvis har brug for at vedligeholde, omformulere eller udvide din kode.

Ofte er en afklaringskommentar en kodelugt. Det fortæller dig, at din kode er for kompleks. Du bør stræbe efter at fjerne afklaringskommentarer og i stedet forenkle koden, fordi "god kode er selvdokumenterende."

Her er et eksempel på en dårlig - dog meget underholdende - afklaringskommentar.

/* * Replaces with spaces * the braces in cases * where braces in places * cause stasis.**/ $str = str_replace(array("\{","\}")," ",$str);

I stedet for at dekorere et lidt forvirrende udsagn med et klogt rim - ikke mindst i amfibrach-dimeter - ville forfatteren have haft det meget bedre at bruge tid på en funktion, der gør selve koden lettere at læse og forstå. Måske en funktion navngivet, removeCurlyBraceskaldet fra en anden funktion navngivet sanitizeInput?

Gør mig ikke forkert, der er tidspunkter - især når du slår igennem en knusende arbejdsbyrde - hvor injektion af lidt humor kan være godt for sjælen. Men når du skriver en sjov kommentar for at kompensere for dårlig kode, gør det faktisk mindre sandsynligt, at folk refaktorerer og retter koden senere.

Vil du virkelig være den, der er ansvarlig for at fratage alle fremtidige kodere glæden ved at læse det kloge lille rim? De fleste kodere humrer og bevæger sig videre uden at ignorere kodelugt.

Der er også tidspunkter, hvor du støder på en kommentar, der er overflødig. Hvis koden allerede er enkel og åbenbar, er der ingen grund til at tilføje en kommentar.

Ligesom, gør ikke denne vrøvl:

/*set the value of the age integer to 32*/int age = 32;

Alligevel er der tidspunkter, hvor uanset hvad du gør med selve koden, er der stadig behov for en afklaringskommentar.

Normalt sker dette, når du har brug for at tilføje en kontekst til en ikke-intuitiv løsning.

Her er et godt eksempel fra Lodash:

function addSetEntry(set, value) { /* Don't return `set.add` because it's not chainable in IE 11. */ set.add(value); return set; }

Der er også tidspunkter, hvor det - efter en masse tanker og eksperimenter - viser sig, at den tilsyneladende naive løsning på et problem faktisk er den bedste. I disse scenarier er det næsten uundgåeligt, at nogle andre koder kommer rundt og tænker, at de er meget klogere end du er og begynder at rode med koden, kun for at opdage, at din vej var den bedste måde hele tiden.

Nogle gange er den anden kodeur dit fremtidige selv.

I disse tilfælde er det bedst at spare alle tid og forlegenhed og efterlade en kommentar.

Følgende mock-kommentar fanger dette scenario perfekt:

/**Dear maintainer: Once you are done trying to 'optimize' this routine,and have realized what a terrible mistake that was,please increment the following counter as a warningto the next guy: total_hours_wasted_here = 42**/

Igen handler ovenstående mere om at være sjov end at være hjælpsom. Men du SKAL efterlade en kommentar, der advarer andre om ikke at forfølge en tilsyneladende åbenbar "bedre løsning", hvis du allerede har prøvet og afvist den. Og når du gør det, skal kommentaren angive, hvilken løsning du prøvede, og hvorfor du besluttede dig imod den.

Her er et simpelt eksempel i JavaScript:

/* don't use the global isFinite() because it returns true for null values*/Number.isFinite(value)

Den grimme

Så vi har set på det gode og det dårlige, men hvad med det grimme?

Desværre er der tidspunkter i ethvert job, hvor du finder dig selv frustreret, og når du skriver kode for at leve, kan det være fristende at lufte den frustration i kodekommentarer.

Arbejd med nok kodebaser, og du vil komme på tværs af kommentarer, der spænder fra kynisk og deprimerende til mørkt og ondskabsfuldt.

Ting som det tilsyneladende harmløse ...

/*This code sucks, you know it and I know it. Move on and call me an idiot later.*/

... til det ligefremme middel

/* Class used to workaround Richard being a f***ing idiot*/

Disse ting kan virke sjove eller kan hjælpe med at frigøre en smule frustration i øjeblikket, men når de gør det til produktionskode, ender de med at få koderen, der skrev dem, og deres arbejdsgiver ser uprofessionel og bitter ud.

Gør ikke dette.

Hvis du nød denne artikel, skal du smadre applaus-ikonet en række gange for at hjælpe med at sprede budskabet. Og hvis du vil læse flere ting som dette, skal du tilmelde dig mit ugentlige Dev Mastery-nyhedsbrev nedenfor.