Fordeler og ulemper (men stort sett fordeler) med kommentarer i kode

Bilde: scyther5, Getty Images / iStockphoto

Bør du legge kommentarer til koden din eller ikke? Svaret er selvfølgelig ja. Det er heller ikke nei. Eller mindre fasitært: "Du bør først strebe etter å gjøre koden din så enkel som mulig å forstå uten å stole på kommentarer som en krykke. Bare på det punktet der koden ikke kan gjøres lettere å forstå, bør du begynne å legge til kommentarer." Jeff Atwood skrev det tilbake i 2006, men det er like relevant i dag som det den gang. Kanskje mer.

Hvordan bygge en vellykket utviklerkarriere (gratis PDF)

Saken mot kommentarer

Ta opp emnet, og alltid (og snart) vil noen fortelle deg hvorfor du ikke bør rot koden din med kommentarer. En av de primære klagene på kommentarer er at de legger støy til kodens signal. "God kode er selvdokumenterende, " sier ordtaket, og å legge til kommentarer kan noen ganger tjene til å maskere dårlig kode, og ikke til det bedre. Som Bennett Garner har skrevet:

Dette er ille nok, men problemet blir sammensatt etter hvert som kommentarer blir eldre. Som Marco Bresciani har hevdet: "Ikke tro på kommentarer: de blir aldri oppdatert. Bare koden forteller sannheten." Kommentarer kan ha vært nyttige på et tidspunkt, men når kode endres (og det er vanlig), gjør kommentarene det ofte ikke. Dette lar koden være full av utdaterte kommentarer som kan ende opp med å forvirre snarere enn å avklare. "Ideelt sett vil utviklere oppdatere kommentarene sine når de oppdaterer koden, men dette pleier ikke å skje.

Selvfølgelig støtter de fleste kodeditorer kodefalsing, som skjuler kommentarene og lar utviklere bare se på kildekoden. Men dette antar at kommentarer alltid er dårlige, noe som ikke stemmer. Når kan de være berettiget?

Saken for kommentarer

Prøv så mye du kan for å gjøre koden din til "selvdokumenterende", en ting koden ikke kan gjøre: Forklar hvorfor bak koden. Som Jef Raskin har bemerket, "T den grunnleggende grunnkoden kan aldri være selvdokumenterende, og automatiske dokumentasjonsgeneratorer kan ikke lage det som trengs, er at de ikke kan forklare hvorfor programmet skrives, og begrunnelsen for å velge Denne eller den metoden. De kan ikke diskutere årsakene til at noen alternative tilnærminger ble tatt. " Du kan for eksempel trenge å forklare hvorfor en ikke-intuitiv bane ble ført, som Bill Sourour roper ut, og dermed redde fremtidige utviklere bryet med den mer åpenbare (men gale) tilnærmingen.

Igjen bør den primære vektleggingen være å skrive høy kvalitet, kortfattet kode som (mer eller mindre) forklarer seg selv. Der dette ikke er mulig (og det er ikke alltid det er mulig), "Tenk på kommentarer som prikken over i’en, som finnes for å gi leseren informasjon som ikke lett kan uttrykkes i selve koden, " for å bruke Brian Hannaways ord.

Det er viktig, fortsetter han, at det er viktig å ha publikum i tankene. Det er en dårlig forutsetning å tro at de som kommer på koden din senere vil ha samme nivå av kompetanse. Som sådan har han antydet å imøtekomme de mindre erfarne:

I sum er det store grunner til å holde kommentarer til et minimum, men de unngår ikke behovet for kommentarer helt. Du trenger påfølgende utviklere for å kunne forstå koden din: Det begynner med å skrive ren, kortfattet kode, men slutter med akkurat nok kommentar til å hjelpe dem å forstå hvorfor du gjorde ting på en bestemt måte.

Ukens nyhetsbrev med åpen kildekode

Du vil ikke gå glipp av våre tips, opplæringsprogrammer og kommentarer til Linux OS og open source applikasjoner. Leveres tirsdager

Registrer deg i dag

© Copyright 2020 | mobilegn.com