Hjælp andre med at følge din kode lettere
Som programmører eller en del af det tekniske område har vi ofte brug for at læse, analysere og skrive kode regelmæssigt. Nogle koder er nemmere at skrive og følge end andre. Jo klarere koden er, jo hurtigere vil den være at forstå, bruge og bygge videre på. Evnen til at skrive god kode er en væsentlig færdighed for enhver programmør eller dataforsker.
Men en af de andre vigtige færdigheder er at skrive gode kommentarer. Nu ved jeg, at hvis du mestrer kunsten at skrive læsbar kode, kan du så skrive færre kommentarer, men vi kan aldrig stoppe med at skrive kommentarer helt for at være realistiske. Så selvom du er god til at skrive kode, skal du også være i stand til at skrive gode kommentarer.
Kommentarer er hoveddelen af enhver god kode. Hvis du åbner en kode, og den ikke har nogen som helst kommentarer, vil det være tidskrævende at læse og forstå den kode. Mangel på kommentarer er lige så slemt som at bruge en overvældende mængde kommentarer. Hvis dine kodefiler er 50 % eller flere kommentarer, så er din kode sandsynligvis ikke særlig velskrevet, hvorfor du havde brug for mange kommentarer for at forklare det.
At skrive gode kommentarer er ikke en vanskelig opgave; det er bare en, der kræver meget øvelse. Heldigvis, hvis du læser denne artikel, er du enten programmør, dataforsker eller arbejder inden for det tekniske område. Det betyder, at du skal skrive/læse meget kode i din karriere.
Så, hvordan skriver man gode kommentarer? I denne artikel vil jeg gennemgå 5 tips til at hjælpe dig med at skrive bedre kommentarer og tage dine evner til at skrive kommentarer til det næste niveau.
Tip 1: Hold det kort, præcist og til sagen
Når det kommer til at skrive kommentarer, vil jeg sige, less is more. Prøv ikke at overforklare hvert trin i koden. Hold dine kommentarer korte, inden for 3 sætninger til klasser og funktioner og en sætning med in-line kommentarer. Hvis din kode er velskrevet, behøver du ikke mange kommentarer for at forklare den. Du behøver kun at give brugerne (medprogrammører) et hint om, hvorfor du har truffet bestemte beslutninger og den overordnede funktionalitet af de forskellige kodesektioner.
Som en generel regel for at holde tingene organiseret og ensartet. beløb programmeringsfællesskabet, når du skriver kommentarer (docstring) til en klasse, skal du inkludere en kort beskrivelse og dato for den sidste ændring. Men når du skriver en til en funktion, skal den indeholde en beskrivelse af dens formål, parametre og resultater.
Tip 2: Bevar den samme stil for hvert niveau
Ofte er koder opdelt i patroner, funktioner, klasser, moduler, biblioteker osv. Hver af disse kan opfattes som et niveau af koden. Derfor, når du skriver kommentarer, er det bedre at udvikle en specifik stil for hvert niveau og vedligeholde den i din kode.
Så du vil bruge den samme stil til at skrive docstring til alle dine kodefunktioner; det samme gælder dine funktioner og dine in-line kommentarer. Det vil hjælpe alle, der læser koden, med at gå hurtigt igennem den og forstå dens struktur uden at skulle læse den i dybden.
Tip 3: Skriv kommentarer før eller mens du skriver kode, og rediger dem derefter
En af de største fejl, begyndere begår, når de først lærer at kode – hvilket jeg også gjorde – er først at skrive den kode og derefter gennemgå koden og skrive kommentarer. Problemet med denne tilgang er, at det ofte tager os et stykke tid at skrive kode, dage eller endda måneder. Så når vi nærmer os skrivetrinnet for kommentarer, havde vi glemt, hvorfor vi tog nogle beslutninger.
I dette tilfælde er den bedste ting at gøre at skrive kommentarer, mens du skriver koden. Nogle programmører siger måske endda, at du skal skrive kommentarerne, før du skriver koden (den vil fungere som en guide for dig). Men efter min mening er det den mest tids- og indsatseffektive tilgang at flytte din kode og dine kommentarer parallelt. Så skriv kommentarer, mens du går, og rediger dem til sidst, hvis det er nødvendigt.
Tip 4: Gør det klart
Kommentarer er ikke kun for folk, der vil læse dine kode i fremtiden; de er også for fremtiden – dig, der vil vedligeholde og udvide det under de næste udviklingstrin. Så at gøre dine kommentarer klare vil hjælpe andre udviklere og dig selv.
“Så snart der er lagt en kodelinje på skærmen, er du i vedligeholdelsestilstand på det stykke kode.” — Phil Haack
Tip 5: Husk at holde det enkelt
Endelig, og måske det mest ligetil, er at holde tingene enkle. Hold din kode enkel, så den ikke behøver en masse forklaring i kommentarerne, mens du holder dine kommentarer enkle og præcise, så andre og fremtidige du finder dem nemme at følge.
En af de grundlæggende programmeringer principper er at lade din kode tale for sig selv. Selvom den bevægelse oprindeligt blev startet af programmører, der ikke kan lide at skrive kommentarer – generelt, de fleste af dem, kan du ikke 100% eliminere kommentarer. Alligevel kan du reducere mængden af dem betydeligt, men at skrive en enklere kode.
Sidste tanker
At blive en succesfuld dataforsker kræver, at du mestrer forskellige færdigheder; programmering er sandsynligvis øverst på listen over disse færdigheder. At være en god programmør betyder, at du kan skrive klar, læsbar kode og kortfattede, klare kommentarer. Begge er lige vigtige for at producere kode af høj kvalitet. De fleste mennesker fokuserer dog mere på at udvikle deres kodeskrivningsfærdigheder og overser arbejdet med deres kommentarer-skrivefærdigheder.
Som enhver anden færdighed er den eneste måde at blive bedre til at skrive kommentarer på at øve sig i at skrive bedre kommentarer. Først skal du læse kommentarer, som du synes er velskrevne, og reflektere over, hvorfor du kunne lide dem. Ofte er korte, klare, beskrivende og ikke overbrugte kommentarer de mest optimale.
Denne artikel gik over 5 tips, der vil tage dine evner til at skrive kommentarer til det næste niveau. Jeg efterlader dig med dette; kommentarer er ikke beregnet til at forklare koden for brugerne; i stedet bruges din kode til at forklare kommentarerne til computeren.