Källkod Kommentar Styling Tips och bästa praxis

Utvecklare som har spenderat tid på stora projekt förstår betydelsen av kodkommentarer. När du bygger många funktioner i samma applikation tenderar saker att bli komplicerade. Det finns så många databitar som funktioner, variabla referenser, returvärden, parametrar ... hur förväntas du fortsätta?

Det bör inte bli någon överraskning att kommentera din kod är nödvändig, både solo och teamprojekt. Men många utvecklare är inte medvetna om hur man ska gå om denna process. Jag har skisserat några av mina egna personliga tricks till skapa snygga, formaterade kodkommentarer. Standarder och kommentarer mallar varierar mellan utvecklare - men i slutändan bör du sträva efter rena och läsliga kommentarer för att förklara förvirrande områden i din kod ytterligare.

Vi bör börja diskutera några av skillnaderna i kommentarformatering. Detta ger dig en bättre uppfattning om hur detaljerad du kan bli med projektkod. Efteråt erbjuder jag några specifika tips och exempel som du kan börja använda direkt!

Kommentar Styles: En översikt

Det bör noteras att dessa idéer presenteras bara riktlinjer mot renare kommentarer. De enskilda programmeringsspråken anger inte riktlinjer eller specifikationer för hur du konfigurerar dokumentationen.

Med det sagt har moderna utvecklare grupperat ihop för att formatera sitt eget system med kodkommentarer. Jag ska erbjuda några vanliga vanliga stilar och gå in i detalj av deras syfte.

Inline Kommentar

Praktiskt taget varje enskilt programmeringsspråk erbjuder inline kommentarer. Dessa är begränsade till enkellinjens innehåll och kommenterar bara texten efter en viss punkt. Så till exempel i C / C ++ börjar du en inline kommentar så här:

// börja variabelnotering var myvar = 1; ... 

Detta är perfekt för att chiming in i koden i några sekunder till förklara eventuellt förvirrande funktionalitet. Om du arbetar med många parametrar eller funktionssamtal kan du placera en rad inline-kommentarer i närheten. Men den mest fördelaktiga användningen är a enkelhetsinriktad förklaring till liten funktionalitet.

om (callAjax ($ params)) // lyckas kör callAjax med användarparametrar ... kod

Observera framför allt koden skulle behöva vara på en ny linje efter öppningsfästet. Annars skulle alla fångas på samma kommentarlinje! Undvik att gå överbord eftersom du i allmänhet inte behöver se enskilda kommentarer helt och hållet på din sida, men speciellt för att förvirra korsningar i koden är det mycket lättare att släppa i sista minuten.

Beskrivande block

När du behöver inkludera en stor förklaring, kommer det inte att vara ett enda liner. Det finns förformaterade kommandomallar som används i ungefär alla områden av programmeringen. Beskrivande block ses mest om funktioner och biblioteksfiler. När du installerar en ny funktion är det bra att lägg till ett beskrivande block ovanför deklarationen.

/ ** * @desc öppnar en modal fönster för att visa ett meddelande * @param string $ msg - meddelandet som ska visas * @return bool - framgång eller misslyckande * / funktion modalPopup ($ msg) ... 

Ovanstående är ett enkelt exempel på en beskrivande funktionskommentar. Jag har skrivit en funktion förmodligen i JavaScript-kallat modalPopup som tar en enda parameter. I kommentarerna ovan har jag använt en syntax som liknar phpDocumentor där varje rad föregås av a @ symbol följt av en vald nyckel. Dessa kommer inte att påverka din kod på något sätt, så du kan skriva @beskrivning istället för @desc utan några ändringar.

Dessa små nycklar kallas faktiskt kommentar taggar som dokumenteras kraftigt på webbplatsen. Känn dig fri att skapa egna och använda dessa som du önskar genom din kod. Jag tycker att de hjälper till att hålla allt som flyter så Jag kan kontrollera viktig information vid en blick. Du bör också märka att jag har använt / * * / blockformat kommentarformat. Detta kommer att hålla allt mycket renare än att lägga till en dubbel snedstreck som börjar vid varje rad.

Grupp / Klass Kommentarer

Förutom att kommentera funktioner och loopar används blockområden inte lika ofta. Där behöver du verkligen starkt blockera kommentarer står i spetsen för dina backend-dokument eller biblioteksfiler. Det är lätt att gå all-out och skriva solid dokumentation för varje fil på din webbplats - vi kan se denna övning i många CMS, som WordPress.

Det högsta området på din sida ska innehålla kommentarer om själva filen. På så sätt kan du Kontrollera snabbt var du redigerar när du arbetar på flera sidor samtidigt. Dessutom kan du använda detta område som En databas för de viktigaste funktionerna du behöver ut ur klassen.

/ ** * @desc denna klass kommer att hålla funktioner för interaktion med användaren * exempel innefattar user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / abstrakt klass myWebClass  

Du kan se att jag har använt bara en liten provklass för den falska myWebClass koda. Jag har lagt till lite metainformation med mitt namn och e-postadress för kontakt. När utvecklare skriver öppen källkod är det i allmänhet bra praxis så att andra kan kontakta dig för support. Detta är också en solid metod när man arbetar i större utvecklingsgrupper.

Taggen @nödvändig är inte något jag har sett använt någon annanstans. Jag har hållit på formatet i några av mina projekt, bara på sidor där jag har anpassat många metoder. När du inkluderar sidor i en fil måste de komma innan du matar ut någon kod. Så att lägga till dessa detaljer i huvudklasskommentaren är ett bra sätt att kom ihåg vilka filer som behövs.

Front-end kod kommenterar

Nu när vi har täckt 3 viktiga kommentarmallar, låt oss titta på några andra exempel. Det finns många frontend-utvecklare som har flyttat från statisk HTML till jQuery och CSS-kod. HTML-kommentarer är inte lika ändamålsenliga i förhållande till programmeringsapplikationer, men när du skriver stilbibliotek och sidskript kan saker bli rörigt över tiden.

JavaScript följer en mer traditionell metod att kommentera liknande Java, PHP och C / C++. CSS använder bara blockformat kommentarer avgränsad av en snedstreck och asterisk. Du bör komma ihåg att kommentarer kommer att öppet visas för besökarna, eftersom varken CSS eller JS analyseras serversidan, men någon av dessa metoder fungerar bra för att lämna informativa godbitar i koden för att gå tillbaka över.

Specifikt bryta upp CSS-filer kan vara en chore. Vi är alla bekanta med att lämna en inline-kommentar för att förklara en åtgärd för Internet Explorer eller Safari. Men jag tror att CSS kommenterar kan användas på nivån jQuery och PHP använder dem. Låt oss dyka in i att skapa stilgrupper innan vi berör några detaljerade tips för kodkommentarer.

CSS stilgrupper

För dem som har utformat CSS i åratal kommer det nästan som en andra natur. Du memorera långsamt alla egenskaper, syntax och bygga ditt eget system för stylesheets. Genom mitt eget arbete har jag skapat det jag kallar gruppering för att para liknande CSS-block i ett område.

När jag går tillbaka för att redigera CSS kan jag lätt hitta vad jag behöver inom några sekunder. Det sätt du väljer att gruppera stilar är helt upp till dig, och det är skönheten i det här systemet. Jag har några förinställda standarder som jag har skisserat nedan:

• @resets - tar bort standardwebbplatsmarginaler, vadderingar, teckensnitt, färger, etc..
• @fonter - stycken, rubriker, blockquotes, länkar, kod
• @navigation - huvudkärnans hemsida navigationslänkar
• @layout - omslag, behållare, sidofält
• @header & @footer - dessa kan variera beroende på din design. Möjliga stilar inkluderar länkar och oordnade listor, sidfot, rubriker, sub-nav

Vid gruppering av stylesheets jag har hittat märkningssystem kan hjälpa mycket. Men till skillnad från PHP eller JavaScript använder jag en singel @grupp tagg följt av en kategori eller nyckelord. Jag har tagit med 2 exempel nedan så att du kan få en känsla för vad jag menar.

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

/ ** @group footer, små teckensnitt, kolumner, externa länkar ** / 

Du kan alternativt lägga till lite extra detalj i varje kommentarblock. Jag väljer att Håll sakerna enkla och raka så stilarken är lätta att skumma. Kommentera handlar om dokumentation så länge du förstår skrivningen är det bra att gå!

4 tips till bättre kommentar Styling

Vi har tillbringat den första halvan av den här artikeln och tittar på de olika formaten för kodkommentarer. Låt oss nu diskutera några övergripande tips för att hålla koden ren, organiserad och lätt att förstå.

1. Håll allt läsbart

Ibland som utvecklare glömmer vi det Vi skriver kommentarer för att människor ska läsa. Alla programmeringsspråk vi förstår är byggda för maskiner, så det kan vara tråkigt att konvertera till vanlig skriftlig text. Det är viktigt att notera att vi inte är här för att skriva ett högskolestudier, men bara lämnar tips!

fungera getTheMail () // kod här kommer att bygga e-post / * run kod om våra egna sendMyMail () funktionsanrop returnerar true hitta sendMyMail () i /libs/mailer.class.php vi kontrollera om användaren fyller i alla fält och meddelandet är skickat! * / if (sendMyMail ()) return true; // vara sant och visa framgång på skärmen

Även ett par ord är bättre än inget. När du går tillbaka för att redigera och arbeta med projekt i framtiden är det ofta förvånande hur mycket du glömmer. Eftersom du inte tittar på samma variabler och funktionsnamn varje dag, tenderar du långsamt att glömma majoriteten av din kod. Således kan du Lämna aldrig för många kommentarer! Men du kan lämna för många dåliga kommentarer.

Som en allmän tumregel, ta lite tid att pausa och reflektera innan du skriver. Fråga dig själv Vad är mest förvirrande om programmet och hur kan du bäst förklara det “dummy” språk? Tänk också på varför skriver du koden exakt som du är.

Några av de mest förvirrande felmen dyker upp när du glömmer syftet med specialbyggda (eller tredje part) funktioner. Lämna ett kommentarspår som leder tillbaka till några andra filer Om det här kommer att hjälpa dig att komma ihåg funktionaliteten enklare.

2. Lätt något utrymme!

Jag kan inte betona nog hur viktigt det är blank kan vara. Detta går dubbelt sant för PHP och Ruby-utvecklare som arbetar på massiva webbplatser med hundratals filer. Du kommer att stirra på den här koden hela dagen! Skulle det inte vara bra om du bara kunde skumma igenom de viktiga områdena?

$ dir1 = "/ home /"; // Ange huvudkatalogen $ myCurrentDir = getCurDirr (); // Ange nuvarande användarkatalog $ userVar = $ get_username (); // nuvarande användarnamn

I exemplet ovan kommer du att märka den extra vaddering som jag har lagt mellan kommentarer och kod på varje rad. När du rullar igenom filer kommer den här kommentaren att kommentera tydligt sticka ut. Det gör att hitta fel och korrigera din kod hundratals gånger lättare när variabla block är så rena.

Du kan utföra en liknande uppgift på koden inuti en funktion där du är förvirrad om hur det fungerar, men den här metoden skulle så småningom röra din kod med inline kommentarer, och det är det exakta motsatsen till ordnad! Jag rekommenderar i detta scenario lägger till en stor block-line kommentar kring logikområdet.

$ (dokument) .ready (funktion () $ ('. sub'). hide (); // göm undernavigering på pageload / ** kolla efter ett klickhändelse på ett ankare inuti .itm div förhindra standardlänken åtgärd så att sidan inte ändras på klickåtkomst. Föräldraelementet i .itm följt av nästa .sub lista för att växla öppna / stänga ** / $ ('. itm a'). live ('klick', funktion ) e.preventDefault (); $ (detta) .parent (). next ('. sub'). slideToggle ('fast');););

Det här är en liten bit av jQuery-kod som riktar sig till en undermenyskjutnavigering. Den första kommentaren är inline för att förklara varför vi gömmer alla .sub klasser. Ovanför händelsehanteraren för live-klick har jag använt en blockkommentar och indented hela skrivandet till samma punkt. Detta gör saker vackerare än löpande stycken - särskilt för andra som läser dina kommentarer.

3. Kommentar medan du kodar

Tillsammans med korrekt avstånd kan detta vara en av de bästa vanorna att komma in i. Ingen vill gå tillbaka över sitt program när det fungerar och dokumenterar varje bit. De flesta av oss vill inte ens gå tillbaka och dokumentera de förvirrande områdena! Det tar verkligen mycket arbete.

Men om du kan skriva kommentarer medan du kodar allt kommer fortfarande att vara friskt i ditt sinne. Vanligtvis kommer utvecklare att fastna på ett problem och skura nätet för den enklaste lösningen. När du träffar Eureka-ögonblicket och löser ett sådant problem finns det i allmänhet ett ögonblick i klarhet där du förstår dina tidigare fel. Detta skulle vara lämpligast tid att lämna öppna och ärliga kommentarer om din kod.

Dessutom kommer detta att ge dig övning att vänja sig på att kommentera alla dina filer. Den tid som krävs för att gå tillbaka och ta reda på hur något fungerar är mycket större efter att du redan har byggt upp funktionen. Både ditt framtida själv och dina lagkamrater kommer att tacka för att du lämnat kommentarer i förväg.

4. Hantera Buggy Fel

Vi kan inte alla sitta framför datorn i timmar för att skriva kod. Jag antar att vi kan försöka, men någon gång behöver vi sova! Du kommer sannolikt att behöva dela sätt med din kod för dagen med vissa funktioner som fortfarande är trasiga. I detta scenario är det viktigt att du lämna långa, detaljerade kommentarer om var du lämnade saker av.

Även efter en ny natts sömn kan du bli förvånad över hur svårt det kan vara att komma tillbaka till koden. Till exempel om du bygger en bilduppladdningssida och måste lämna den ofullständig, du bör kommentera var i processen du lämnade. Bilder uppladdas och lagras i tempminnet? Eller kanske erkänns de inte ens i uppladdningsformuläret, eller kanske visas de inte korrekt på sidan efter uppladdning.

Kommentarfel är viktigt för två huvudorsaker. Först kan du enkelt plocka upp var du slutade och försök igen färskt i åtanke för att åtgärda problemet (erna). Och för det andra kan du skilja mellan den levande produktionsversionen av din webbplats och testplatsen. Kom ihåg att kommentarer ska användas till förklara varför du gör något, inte exakt vad det gör.

Slutsats

Utveckling för webbapps och programvara är en uppföljande övning, om än svår. Om du är en av de få utvecklarna som verkligen förstår att bygga programvara är det viktigt att mogna med dina kodningsförmågor. Att lämna beskrivande kommentarer är bara bra praxis på lång sikt, och du kommer troligen aldrig ångra det!

Om du har förslag på tydligare kodkommentarer, låt oss veta i diskussionsområdet nedan!