Kildekode Kommentar Styling Tips og bedste praksis

Udviklere, der har brugt nogen tid på store projekter, forstår vigtigheden af ​​kode kommentarer. Når du bygger mange funktioner i samme applikation, har tingene tendens til at blive komplicerede. Der er så mange databits, herunder funktioner, variable referencer, returværdier, parametre ... hvordan forventes det at holde op?

Det bør ikke være nogen overraskelse, at kommentere din kode er afgørende, både solo og team projekter. Men mange udviklere er uvidende om, hvordan man skal gå om denne proces. Jeg har skitseret nogle af mine egne personlige tricks til skaber pæne, formaterede kode kommentarer. Standarder og kommentarskabeloner vil variere mellem udviklere - men i sidste ende skal du stræbe efter rene og læsbare kommentarer for yderligere at forklare forvirrende områder i din kode.

Vi bør begynde at diskutere nogle af forskellene i kommentarformatering. Dette vil give dig en bedre ide om, hvor detaljeret du kan blive med projektkode. Bagefter vil jeg tilbyde nogle specifikke tips og eksempler, som du kan begynde at bruge med det samme!

Kommentar Styles: En oversigt

Det skal bemærkes, at disse ideer, der præsenteres, kun er retningslinier i retning af renere kommentarer. De enkelte programmeringssprog fastsætter ikke retningslinjer eller specifikationer for, hvordan du opsætter din dokumentation.

Når det er sagt, har moderne udviklere grupperet sammen for at formatere deres eget system med kodekommentarer. Jeg vil tilbyde nogle få mainstream-stilarter og gå i detaljer i deres formål.

Inline Kommentar

Næsten alle programmeringssprog tilbyder inline kommentarer. Disse er begrænset til enkeltlinjens indhold og kommenterer kun teksten efter et bestemt punkt. Så for eksempel i C / C ++ begynder du en inline-kommentar som denne:

// start variabel liste var myvar = 1; ... 

Dette er perfekt til at chimere ind i koden i et par sekunder til Forklar muligvis forvirrende funktionalitet. Hvis du arbejder med mange parametre eller funktionsopkald, kan du placere en masse inline-kommentarer i nærheden. Men den mest fordelagtige brug er en simple-minded forklaring på lille funktionalitet.

hvis (callAjax ($ params)) // med succes køre callAjax med brugerparametre ... kode

Bemærk først og fremmest, at koden skal være på en ny linje efter åbningsbøjlen. Ellers ville det alle blive fanget på samme kommentarlinje! Undgå at gå over bord da du generelt ikke behøver at se single-line kommentarer helt ned på din side, men især for at forvirre kryds i din kode, er disse meget nemmere at falde i sidste øjeblik.

Beskrivende blokke

Når du skal medtage en stor forklaring, vil en enkelt liner normalt ikke gøre tricket. Der er præformaterede kommandoskabeloner, der bruges i næsten alle programmeringsområder. Beskrivende blokke ses især omkring funktioner og biblioteksfiler. Når du opsætter en ny funktion, er det god praksis at Tilføj en beskrivende blok over erklæringen.

/ ** * @desc åbner et modalt vindue for at vise en besked * @param string $ msg - meddelelsen skal vises * @return bool - succes eller fiasko * / funktion modalPopup ($ msg) ... 

Ovenstående er et simpelt eksempel på en beskrivende funktionskommentar. Jeg har skrevet en funktion formodentlig i JavaScript kaldet modalPopup som tager en enkelt parameter. I kommentarerne ovenfor har jeg brugt en syntaks svarende til phpDocumentor, hvor hver linje foregår med a @ symbol efterfulgt af en valgt nøgle. Disse vil ikke påvirke din kode på nogen måde, så du kunne skrive @beskrivelse i stedet for @desc uden ændringer overhovedet.

Disse små nøgler kaldes faktisk kommentar tags som dokumenteres stærkt på hjemmesiden. Du er velkommen til at lave dine egne og bruge disse som du ønsker i hele din kode. Jeg finder, at de hjælper med at holde alt flydende Jeg kan kontrollere vigtige oplysninger et øjeblik. Du skal også bemærke, at jeg har brugt / * * / blokformat kommentarformat. Dette vil holde alt meget renere end at tilføje en dobbelt skråstreg, der starter ved hver linje.

Gruppe / Klasse Kommentarer

Udover at kommentere funktioner og sløjfer benyttes blokarealer ikke så ofte. Hvor har du virkelig brug for stærk blokere kommentarer står i spidsen for dine backend-dokumenter eller biblioteksfiler. Det er nemt at gå all-out og skrive solid dokumentation for hver fil på dit website - vi kan se denne praksis i mange CMS som WordPress.

Det aller øverste område på din side skal indeholde bemærkninger til selve filen. På denne måde kan du Kontroller hurtigt, hvor du redigerer når du arbejder på flere sider på samme tid. Derudover kan du bruge dette område som en database til de vigtigste funktioner, du har brug for ud af klassen.

/ ** * @desc denne klasse vil holde funktioner for brugerinteraktion * Eksempler omfatter bruger_pass (), bruger_brugernavn (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / abstrakt klasse myWebClass  

Du kan se, jeg har brugt bare en lille prøveklasse til den falske myWebClass kode. Jeg har tilføjet nogle meta-oplysninger med mit navn og e-mail-adresse til kontakt. Når udviklere skriver open source-kode, er det generelt god praksis, så andre kan kontakte dig for at få hjælp. Dette er også en solid metode, når man arbejder i større udviklingshold.

Tagget @required er ikke noget, jeg har set brugt andre steder. Jeg har holdt op med formatet i nogle af mine projekter, kun på sider, hvor jeg har tilpasset mange metoder. Når du inkludere sider i en fil, skal de komme, før du udsender en kode. Så det er en god måde at tilføje disse detaljer i hovedklassens kommentarblok Husk hvilke filer der er behov for.

Front-end kode Kommentar

Nu hvor vi har dækket 3 vigtige kommentarskabeloner, lad os se på et par andre eksempler. Der er mange frontend-udviklere, der er flyttet fra statisk HTML til jQuery og CSS-kode. HTML-kommentarer er ikke så målbevidste i forhold til programmeringsapplikationer, men når du skriver stilbiblioteker og sideskripter, kan tingene blive rodet over tid.

JavaScript følger en mere traditionel metode til at kommentere ligner Java, PHP og C / C++. CSS bruger kun blok-stil kommentarer afgrænset af en skråstreg og asterisk. Du skal huske på, at kommentarer vil blive åbent vist for dine besøgende, da hverken CSS eller JS er parsed server-side, men en af ​​disse metoder fungerer fint, når du forlader informative klip i din kode for at gå tilbage.

Specielt opbrud af CSS-filer kan være en opgave. Vi er alle bekendt med at efterlade en inline-kommentar for at forklare en løsning til Internet Explorer eller Safari. Men jeg tror, ​​at CSS kommenterer kan bruges på niveau jQuery og PHP bruger dem. Lad os dvæle ind i at oprette stilgrupper, før vi rører nogle detaljerede tips til kodekommentarer.

CSS stilgrupper

For dem, der har designet CSS i årevis, kommer det næsten som en anden natur. Du husker langsomt alle egenskaber, syntaks og opbygger dit eget system til stylesheets. Gennem mit eget arbejde har jeg skabt det jeg kalder gruppering at sammenkoble lignende CSS-blokke til et område.

Når jeg går tilbage til at redigere CSS, kan jeg nemt finde det, jeg har brug for om få sekunder. Den måde du vælger at gruppere stilarter på, er helt op til dig, og det er skønheden i dette system. Jeg har fået nogle forudindstillede standarder, som jeg har beskrevet nedenfor:

• @resets - fjerner standard browsermarginer, polstring, skrifttyper, farver osv.
• @fonter - afsnit, overskrifter, blokeringer, links, kode
• @navigation - de vigtigste kerne website navigation links
• @layout - wrapper, container, sidebars
• @header & @footer - disse kan variere baseret på dit design. Mulige stilarter omfatter links og uordnede lister, footer-kolonner, overskrifter, undernavne

Når jeg grupperer stylesheets, har jeg fundet tagging system kan hjælpe meget. Men i modsætning til PHP eller JavaScript bruger jeg en enkelt @gruppe tag efterfulgt af en kategori eller søgeord. Jeg har medtaget 2 eksempler nedenfor, så du kan få en fornemmelse for hvad jeg mener.

/ ** @group footer * / #footer styles ...

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

Du kan alternativt tilføje lidt ekstra detaljer i hver kommentarblok. Jeg vælger at holde tingene enkle og ligefrem så stilarkene er nemme at skumme. Kommentering handler om dokumentation, så længe du forstår skrivningen er det godt at gå!

4 tips til bedre kommentar styling

Vi har brugt den første halvdel af denne artikel og kigger på de forskellige formater til kodekommentarer. Lad os nu diskutere nogle overordnede tips til at holde din kode ren, organiseret og let at forstå.

1. Hold alt læsbart

Nogle gange som udviklere glemmer vi det Vi skriver kommentarer til, at mennesker kan læse. Alle de programmeringssprog, vi forstår, er bygget til maskiner, så det kan være kedeligt at konvertere til almindelig skrevet tekst. Det er vigtigt at bemærke, at vi ikke er her for at skrive et kollegium-niveau forskningsarkiv, men bare forlader tips!

funktion getTheMail () // kode her vil opbygge e-mail / * kør kode, hvis vores tilpassede sendMyMail () funktionsopkald returnerer sandt find sendMyMail () i /libs/mailer.class.php vi kontrollerer, om brugeren udfylder alle felter og beskeden er sendt! * / hvis (sendMyMail ()) return true; // være sandt og vis skærmens succes

Selv om blot et par ord er bedre end ingenting. Når du går tilbage til at redigere og arbejde på projekter i fremtiden, er det ofte overraskende, hvor meget du vil glemme. Da du ikke ser på de samme variabler og funktionsnavne hver dag, har du tendens til langsomt at glemme størstedelen af ​​din kode. Således kan du Forlad aldrig for mange kommentarer! Men du kan forlade for mange dårlige kommentarer.

Som en generel tommelfingerregel, tag lidt tid til at sætte pause og reflektere inden du skriver. Spørge dig selv Hvad er mest forvirrende om programmet og hvordan kan du bedst forklare det “dummy” Sprog? Overvej også hvorfor skriver du koden præcis som du er.

Nogle af de mest forvirrende fejl dukker op, når du glemmer formålet med specialbyggede (eller tredjeparts) funktioner. Forlad et kommentarspor, der fører tilbage til et par andre filer hvis dette vil hjælpe dig med at huske funktionaliteten lettere.

2. lindre noget rum!

Jeg kan ikke understrege nok, hvor vigtigt det er hvidt rum måske. Dette går dobbelt sandt til PHP og Ruby-udviklere, der arbejder på massive websites med hundredvis af filer. Du vil stirre på denne kode hele dagen lang! Ville det ikke være godt, hvis du bare kunne skimme igennem til de vigtige områder?

$ dir1 = "/ home /"; // Indstil hovedkataloget $ myCurrentDir = getCurDirr (); // indstil den aktuelle brugerkatalog $ userVar = $ get_username (); // nuværende brugerens brugernavn

I eksemplet ovenfor vil du bemærke den ekstra polstring jeg har placeret imellem kommentarer og kode på hver linje. Når du ruller gennem filer, vil denne stil kommenteres tydeligt skiller sig ud. Det gør det muligt at finde fejl og korrigere din kode hundredvis af gange lettere når variable blokke er så ren.

Du kan udføre en lignende opgave på koden inde i en funktion, hvor du er forvirret om, hvordan det virker, men denne metode vil i sidste ende forstyrre din kode med inline-kommentarer, og det er det nøjagtige modsatte af ordnet! Jeg anbefaler i dette scenario tilføjer en stor blok-line kommentar omkring logikområdet.

$ (dokument) .ready (funktion () $ ('. sub'). skjul (); // skjul undernavigation på pageload / ** check for et klikhændelse på et anker indeni .itm div forhindrer standard link handling, så siden ændres ikke ved klikadgang. Forældreelementet i .itm efterfulgt af den næste .sub liste for at skifte åbne / lukke ** / $ ('. itm a'). live ('klik', funktion ) e.preventDefault (); $ (dette) .parent (). næste ('. sub'). slideToggle ('fast');););

Dette er en lille smule jQuery-kode, der målretter mod en undermenu glidende navigation. Den første kommentar er inline for at forklare, hvorfor vi gemmer alt .sub klasser. Over live-klikhændelseshåndtereren har jeg brugt en blokkommentar og indrykkede hele skrivningen til det samme punkt. Dette gør tingene smukkere i stedet for run-on afsnit - især for andre at læse dine kommentarer.

3. Kommentar under kodning

Sammen med ordentlig afstand kan dette være et af de bedste vaner at komme ind på. Ingen ønsker at gå tilbage over deres program, efter at det virker og dokumenterer hvert stykke. De fleste af os ønsker ikke engang at gå tilbage og dokumentere de forvirrende områder! Det tager virkelig meget arbejde.

Men hvis du kan skrive kommentarer, mens du kodes alt vil stadig være frisk i dit sind. Typisk udviklere vil sætte sig fast på et problem og skure nettet for den nemmeste løsning. Når du rammer Eureka-øjeblikket og løser et sådant problem, er der generelt et øjeblik i klarhed, hvor du forstår dine tidligere fejl. Dette ville være bedste tid at forlade åbne og ærlige kommentarer om din kode.

Derudover vil dette øve dig til at vænne sig til at kommentere alle dine filer. Den tid, der kræves for at gå tilbage og finde ud af, hvordan noget virker, er meget større, efter at du allerede har opbygget funktionen. Både din fremtidige selv og dine holdkammerater vil takke dig for at give kommentarer før tiden.

4. Håndtering af fejl i buggy

Vi kan ikke alle sidde foran computeren i timevis skrive kode. Jeg formoder, at vi kan prøve, men på et tidspunkt skal vi sove! Du vil sandsynligvis nødt til at dele veje med din kode for dagen med nogle funktioner, der stadig er brudt. I dette scenario er det afgørende, at du Forlad lange, detaljerede kommentarer om, hvor du forlod tingene.

Selv efter en frisk nats søvn kan du blive overrasket over, hvor svært det kan være at komme tilbage til kodenes sving. For eksempel, hvis du opbygger en billede upload side og skal lade den være ufuldstændig, du skal kommentere hvor i processen du slap. Bliver billederne uploadet og gemt i temphukommelse? Eller måske anerkendes de ikke engang i uploadformularen, eller måske vises de ikke korrekt på siden efter upload.

Kommentarfejl er vigtig af to hovedårsager. Først kan du nemt afhente hvor du slap af og prøv igen frisk i tankerne for at løse problemet (erne). Og for det andet kan du skelne mellem live produktion version af dit websted og test grunde. Husk at kommentarer skal bruges til forklar hvorfor du gør noget, ikke præcis hvad det gør.

Konklusion

Udvikling til web apps og software er en tilfredsstillende praksis, omend en vanskelig. Hvis du er en af ​​de få udviklere, der virkelig forstår at bygge software, er det vigtigt at modne med dine kodningsevner. Forladende beskrivende bemærkninger er bare god praksis på lang sigt, og du vil sandsynligvis aldrig fortryde det!

Hvis du har forslag til klarere kodekommentarer, så lad os vide det i diskussionsområdet nedenfor!