Kildekode Kommentar Styling Tips og beste praksis

Utviklere som har brukt tid på store prosjekter, forstår viktigheten av kodekommentarer. Når du bygger mange funksjoner i samme applikasjon, har det en tendens til å bli komplisert. Det er så mange databit inkludert funksjoner, variable referanser, returverdier, parametre ... hvordan forventes det å holde tritt?

Det bør ikke komme som en overraskelse at kommentaren din er viktig, både solo og teamprosjekter. Men mange utviklere er uvitende om hvordan man skal gå om denne prosessen. Jeg har skissert noen av mine egne personlige triks til skaper pent, formatert kode kommentarer. Standarder og kommentarsjablonger vil variere mellom utviklere - men til slutt bør du streve mot rene og lesbare kommentarer for å forklare forvirrende områder i koden din.

Vi bør begynne å diskutere noen av forskjellene i kommentarformatering. Dette gir deg en bedre ide om hvor detaljert du kan bli med prosjektkode. Etterpå vil jeg tilby noen spesifikke tips og eksempler som du kan begynne å bruke med en gang!

Kommentar Styles: En oversikt

Det skal bemerkes at disse ideene som presenteres er bare retningslinjer mot renere kommentarer. De enkelte programmeringsspråk angir ikke retningslinjer eller spesifikasjoner for hvordan du konfigurerer dokumentasjonen.

Når det er sagt, har dagens utviklere gruppert sammen for å formatere sitt eget system med kodekommentarer. Jeg vil tilby noen vanlige ordinære stiler og gå i detalj av deres formål.

Inline kommenterer

Nesten hvert enkelt programmeringsspråk tilbyr inline kommentarer. Disse er begrenset til enkeltlinjeinnhold og bare kommenterer teksten etter et bestemt punkt. Så for eksempel i C / C ++ begynner du en inline-kommentar som dette:

// begynn variabel notering var myvar = 1; ... 

Dette er perfekt for å chiming inn i koden i noen sekunder til Forklar muligens forvirrende funksjonalitet. Hvis du jobber med mange parametere eller funksjonsanrop, kan du legge inn en rekke innlinjeproblemer i nærheten. Men den mest fordelaktige bruken er a Enkeltsinnet forklaring på liten funksjonalitet.

hvis (callAjax ($ params)) // vellykket kjøre callAjax med brukerparametere ... kode

Legg merke til at alt koden må være på en ny linje etter åpningsbraketten. Ellers ville det bli fanget på samme kommentarlinje! Unngå å gå over bord siden du vanligvis ikke trenger å se single-line kommentarer helt ned på siden din, men spesielt for å forvirre kryss i koden din, er disse mye enklere å slippe i siste øyeblikk.

Beskrivende blokker

Når du trenger å inkludere en stor forklaring, vil en enkelt liner vanligvis ikke gjøre trikset. Det finnes forhåndsformatte kommentarsjablonger som brukes i omtrent hvert område av programmering. Beskrivende blokker er mest sett rundt funksjoner og biblioteksfiler. Når du setter opp en ny funksjon, er det god praksis å legg til en beskrivende blokk over erklæringen.

/ ** * @desc åpner et modalt vindu for å vise en melding * @param string $ msg - meldingen som skal vises * @return bool - suksess eller fiasko * / funksjon modalPopup ($ msg) ... 

Ovenfor er et enkelt eksempel på en beskrivende funksjonskommentar. Jeg har skrevet en funksjon antagelig i JavaScript-kalt modalPopup som tar en enkelt parameter. I kommentarene ovenfor har jeg brukt et syntaks som ligner på phpDocumentor, hvor hver linje foregår med a @ symbolet etterfulgt av en valgt tast. Disse vil ikke påvirke koden din på noen måte, så du kan skrive @beskrivelse i stedet for @desc uten endringer overhodet.

Disse små nøklene kalles faktisk kommentarkoder som er dokumentert tungt på nettsiden. Ta gjerne med deg selv og bruk disse som du ønsker i hele koden din. Jeg finner de bidrar til å holde alt flyter så Jeg kan sjekke viktig informasjon på et øyeblikk. Du bør også legge merke til at jeg har brukt / * * / blokkformat kommentarsformat. Dette vil holde alt mye renere enn å legge til en dobbel skråstrek som begynner på hver linje.

Gruppe / Klasse Kommentarer

Bortsett fra å kommentere funksjoner og sløyfer, blir blokkarealer ikke utnyttet så ofte. Hvor du virkelig trenger sterk blokkere kommentarer er på hodet av dokumentene dine eller arkivfilene. Det er enkelt å gå all-out og skrive solid dokumentasjon for hver fil på nettstedet ditt - vi kan se denne øvelsen i mange CMS, for eksempel WordPress.

Det aller beste området på siden din skal inneholde kommentarer angående selve filen. På denne måten kan du Sjekk raskt hvor du redigerer når du jobber på flere sider samtidig. I tillegg kan du bruke dette området som en database for de viktigste funksjonene du trenger ut av klassen.

/ ** * @desc denne klassen vil holde funksjoner for brukerinteraksjon * eksempler inkluderer user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / abstrakt klasse myWebClass  

Du kan se jeg har brukt bare en liten prøveklasse for den falske myWebClass kode. Jeg har lagt til noen meta-informasjon med mitt navn og e-postadresse for kontakt. Når utviklere skriver åpen kildekode, er dette generelt god praksis, slik at andre kan kontakte deg for å få hjelp. Dette er også en solid metode når man arbeider i større utviklingsgrupper.

Merket @required er ikke noe jeg har sett brukt andre steder. Jeg har holdt opp med formatet i noen av mine prosjekter, bare på sider der jeg har tilpasset mange metoder. Når du inkludere sider i en fil, må de komme før du skriver ut en kode. Så å legge disse detaljene i hovedklassen kommentaren blokk er en god måte å husk hvilke filer som trengs.

Front-end-kode kommenterer

Nå som vi har dekket 3 viktige kommentarmaler, la oss se på noen andre eksempler. Det er mange frontend-utviklere som har flyttet fra statisk HTML til jQuery og CSS-kode. HTML-kommentarer er ikke like hensiktsmessige i forhold til programmeringsapplikasjoner, men når du skriver stilbiblioteker og sideskript kan ting bli rotete over tid.

JavaScript følger en mer tradisjonell metode for kommentarer som ligner på Java, PHP og C / C++. CSS bruker bare blokkblokkkommentarene avgrenset av et skråstrek og en stjerne. Du bør huske at kommentarer vil bli åpent vist for de besøkende, siden verken CSS eller JS er parsed server-side, men en av disse metodene fungerer bra for å forlate informative godbiter i koden din for å gå tilbake over.

Spesielt bryte opp CSS-filer kan være en rolle. Vi er alle kjent med å forlate en inline-kommentar for å forklare en løsning for Internet Explorer eller Safari. Men jeg tror CSS kommenterer kan brukes på nivå jQuery og PHP bruker dem. La oss dykke inn i å lage stilgrupper før du berører noen detaljerte tips for kodkommentarer.

CSS stilgrupper

For de som har designet CSS i årevis kommer det nesten som en annen natur. Du husker sakte alle egenskapene, syntaksene og bygger ditt eget system for stilark. Gjennom mitt eget arbeid har jeg skapt det jeg kaller gruppering å koble lignende CSS-blokker til ett område.

Når jeg går tilbake for å redigere CSS, kan jeg lett finne det jeg trenger om noen få sekunder. Måten du velger å gruppere stiler, er helt opp til deg, og det er skjønnheten i dette systemet. Jeg har noen forhåndsinnstilte standarder som jeg har skissert nedenfor:

• @resets - tar bort standard nettlesermarginer, polstring, fonter, farger osv.
• @fonter - avsnitt, overskrifter, blokkeringer, linker, kode
• @navigation - hovedkjernens navigasjonslinks
• @layout - wrapper, container, sidebars
• @header & @footer - disse kan variere basert på design. Mulige stiler inkluderer koblinger og uordnede lister, bunntekstkolonner, overskrifter, undernavne

Når jeg har gruppert stilark, har jeg funnet tagging system kan hjelpe mye. Men i motsetning til PHP eller JavaScript bruker jeg en enkelt @gruppe tag etterfulgt av en kategori eller nøkkelord. Jeg har tatt med 2 eksempler nedenfor slik at du kan få en følelse av hva jeg mener.

/ ** @group footer * / #footer stiler ...

/ ** @group footer, små skrifttyper, kolonner, eksterne lenker ** / 

Du kan alternativt legge til litt ekstra detalj i hver kommentarblokk. Jeg velger å Hold ting enkelt og greit slik at stilarkene er enkle å skumme. Kommentering handler om dokumentasjon så lenge du forstår skrivingen, er det godt å gå!

4 tips til bedre kommentar styling

Vi har brukt den første halvdelen av denne artikkelen på å se på de forskjellige formatene for kodekommentarer. La oss nå diskutere noen generelle tips for å holde koden ren, organisert og lett å forstå.

1. Hold alt lesbart

Noen ganger som utviklere glemmer vi det Vi skriver kommentarer for mennesker å lese. Alle programmeringsspråket vi forstår er bygget for maskiner, så det kan være kjedelig å konvertere til vanlig skriftlig tekst. Det er viktig å merke seg at vi ikke er her for å skrive et høyskoleforskningsarkiv, men bare forlater tips!

funksjon getTheMail () // kode her vil bygge e-post / * kjør kode hvis vår egendefinerte sendMyMail () funksjonsanrop returnerer sann finn sendMyMail () i /libs/mailer.class.php vi sjekker om brukeren fyller i alle felt og meldingen er sendt! * / hvis (sendMyMail ()) return true; // vær sant og vis suksess på skjermen

Selv bare et par ord er bedre enn ingenting. Når du går tilbake for å redigere og arbeide med prosjekter i fremtiden, er det ofte overraskende hvor mye du vil glemme. Siden du ikke ser på de samme variablene og funksjonsnavnene hver dag, har du en tendens til å sakte glemme flertallet av koden din. Dermed kan du aldri la for mange kommentarer! Men du kan legge for mange dårlige kommentarer.

Som en generell tommelfingerregel, ta litt tid til å pause og reflektere før du skriver. Spør deg selv hva er mest forvirrende om programmet og hvordan kan du best forklare det “dummy” Språk? Vurder også hvorfor skriver du koden nøyaktig slik du er.

Noen av de mest forvirrende feilene dukker opp når du glemmer formålet med spesialbygde (eller tredjeparts) funksjoner. Legg igjen en kommentarspor som fører tilbake til noen andre filer hvis dette vil hjelpe deg med å huske funksjonaliteten lettere.

2. Løs noen plass!

Jeg kan ikke stress nok hvor viktig mellomrom kan være. Dette går dobbelt sant for PHP og Ruby utviklere som jobber på massive nettsteder med hundrevis av filer. Du vil stirre på denne koden hele dagen! Ville det ikke vært bra hvis du bare kunne skumme gjennom til de viktige områdene?

$ dir1 = "/ home /"; // sett hovedkatalogen $ myCurrentDir = getCurDirr (); // sett gjeldende brukerkatalog $ userVar = $ get_username (); // nåværende brukerens brukernavn

I eksemplet ovenfor vil du legge merke til ekstra utfylling jeg har plassert mellom kommentarer og kode på hver linje. Når du ruller gjennom filer, vil denne kommentaren være tydelig skiller seg ut. Den gjør det mulig å finne feil og korrigere koden din hundrevis av ganger lettere når variable blokker er så ren.

Du kan utføre en lignende oppgave på koden inne i en funksjon der du er forvirret om hvordan det fungerer, men denne metoden vil til slutt knuse koden din med inline-kommentarer, og det er det motsatte av ordnet! Jeg anbefaler i dette scenariet legger til en stor blokkerings kommentar rundt logikkområdet.

$ (dokument) .ready (funksjon () $ ('. sub'). skjul (); // skjul undernavigering på pageload / ** sjekk for et klikkhendelse på et anker inne .itm div forhindrer standard lenken handling, slik at siden ikke endres på klikktilgang, er foreldreelementet til .itm etterfulgt av den neste .sub-listen for å bytte åpne / lukke ** / $ ('.tm'). live ('klikk', funksjon ) e.preventDefault (); $ (dette) .parent (). next ('. sub'). slideToggle ('fast');););

Dette er en liten bit av jQuery-kode som er rettet mot en undermeny glidende navigasjon. Den første kommentaren er inline for å forklare hvorfor vi gjemmer alle .under klasser. Over live click event handler Jeg har brukt en blokk kommentar og innrykket all skriving til samme punkt. Dette gjør ting vakrere i stedet for run-on avsnitt - spesielt for andre som leser dine kommentarer.

3. Kommentar mens du kodes

Sammen med riktig avstand kan dette være en av de beste vanene å komme inn på. Ingen ønsker å gå tilbake over sitt program etter at det har fungert og dokumentert hvert stykke. De fleste av oss ønsker ikke engang å gå tilbake og dokumentere de forvirrende områdene! Det tar virkelig mye arbeid.

Men hvis du kan skrive kommentarene mens du er koding alt vil fortsatt være friskt i tankene dine. Vanligvis vil utviklere bli sittende fast på et problem og skure nettet for den enkleste løsningen. Når du treffer Eureka-øyeblikket og løser et slikt problem, er det generelt et øyeblikk i klarhet hvor du forstår dine tidligere feil. Dette ville være Beste tiden å la åpne og ærlige kommentarer om koden din.

I tillegg vil dette øve deg til å bli vant til å kommentere alle filene dine. Mengden tid som trengs for å gå tilbake og finne ut hvordan noe fungerer, er mye større etter at du allerede har bygget funksjonen. Både din fremtidige selv og dine lagkamerater vil takke deg for å legge igjen kommentarer på forhånd.

4. Håndtere feil med buggy

Vi kan ikke alle sitte foran datamaskinen for timer å skrive kode. Jeg antar at vi kan prøve, men på et tidspunkt må vi sove! Du vil sannsynligvis måtte dele måter med koden din for dagen med noen funksjoner som fortsatt er ødelagte. I dette scenariet er det avgjørende at du gi lange, detaljerte kommentarer om hvor du forlot ting.

Selv etter en ny natts søvn kan du bli overrasket over hvor vanskelig det kan være å komme tilbake til svingningen av kodingen. For eksempel hvis du bygger en bildeopplastingsside og må forlate den ufullstendige, du skal kommentere hvor i prosessen du sluttet. Blir bildene lastet opp og lagret i tempeminnet? Eller kanskje blir de ikke engang anerkjent i opplastingsskjemaet, eller kanskje vises de ikke riktig på siden etter opplasting.

Kommentarfeil er viktig for to hovedårsaker. Først kan du lett plukke opp hvor du sluttet og prøv igjen frisk i tankene for å fikse problemet (e). Og det andre kan du skille mellom liveproduksjonsversjonen av nettstedet ditt og testområdet. Husk at kommentarer skal brukes til Forklar hvorfor du gjør noe, ikke akkurat hva det gjør.

Konklusjon

Utvikling for webapps og programvare er en tilfredsstillende praksis, om enn vanskelig. Hvis du er en av de få utviklerne som virkelig forstår å bygge programvare, er det viktig å modne med dine kodingsevner. Å forlate beskrivende kommentarer er bare god praksis i det lange løp, og du vil sannsynligvis ikke angre på det!

Hvis du har forslag til klarere kodekommentarer, vennligst gi oss beskjed i diskusjonsområdet nedenfor!