Lähtekoodi kommentaaride kujundamise näpunäited ja parimad tavad

Arendajad, kes on veetnud aega suurprojektides, mõistavad koodi kommentaaride tähtsust. Kui ehitate samasse rakendusse palju funktsioone, kipuvad asjad keerukaks muutuma. Seal on nii palju andmebitte, mis sisaldavad funktsioone, muutuvaid viiteid, tagastusväärtusi, parameetreid ... kuidas te eeldatavasti jätkate?

Pole üllatav, et teie koodi kommenteerimine on oluline nii soolo- kui ka meeskonnaprojektide puhul. Kuid paljud arendajad ei ole sellest protsessist teadlikud. Olen kirjeldanud mõningaid oma isiklikke trikke luua puhas, vormindatud koodi kommentaarid. Standardid ja kommentaarimallid on arendajate vahel erinevad, kuid lõpuks peaksite püüdlema puhtad ja loetavad kommentaarid selgitada oma koodi segadust tekitavaid valdkondi.

Peaksime alustama mõnede kommentaaride vormindamise erinevuste arutamist. See annab teile parema ettekujutuse sellest, kui üksikasjalikult saate projekti koodiga tutvuda. Seejärel pakun teile mõned konkreetsed nõuanded ja näited, mida saate kohe kasutada!

Kommentaaride stiilid: ülevaade

Tuleb märkida, et esitatud ideed on vaid suunised puhtamate märkuste poole. Individuaalsed programmeerimiskeeled ei sisalda juhiseid ega spetsifikatsioone dokumentatsiooni seadistamiseks.

See tähendab, et tänapäeva arendajad on rühmitanud oma koodi kommenteerimise süsteemi. Pakun paar peavoolu stiili ja läheme nende eesmärgi juurde.

Inline kommenteerimine

Praktiliselt pakub iga programmeerimiskeel inline kommentaarid. Need on piiratud ühe reaga sisuga ja kommenteerivad teksti ainult teatud punkti järel. Nii näiteks alustate C / C + + puhul sellist sisemist kommentaari:

// algab muutujate loetelu var myvar = 1; 

See sobib ideaalselt koodile mõne sekundi väljumiseks seletada võimalikku segadust. Kui te töötate paljude parameetrite või funktsioonikõnedega, võite paigutada lähedalasuvaid kommentaare. Kuid kõige kasulikum kasutamine on a väikese funktsionaalsuse lihtsat mõistmist.

kui (callAjax ($ params)) // käivitas callAjaxi edukalt kasutaja parameetritega ... kood

Kõigepealt peab teade, et kood oleks pärast avamisklambrit uus rida. Vastasel juhul jääks see kõik samasse kommentaari reale! Vältige sõitmist üle parda kuna te ei pea tavaliselt oma lehekülje alla ühe rea märkusi nägema, kuid eriti teie koodi segaduste segamiseks, on need viimasel minutil palju lihtsamad..

Kirjeldavad plokid

Kui teil on vaja lisada suur selgitus, ei tee üks vooder trikki. Kõigis programmeerimisvaldkondades kasutatakse eelnevalt vormindatud kommentaari malle. Kirjeldavad plokid kõige olulisem on näha funktsioone ja raamatukogu faile. Kui seadistate uue funktsiooni, on see hea tava lisage deklaratsiooni kohal kirjeldav plokk.

/ ** * @desc avab modaalse akna, et kuvada teade * @param string $ msg - kuvatav teade * @return bool - edu või ebaõnnestumine * / funktsioon modalPopup ($ msg) … 

Eespool on lihtne näide kirjeldava funktsiooni kommentaarist. Ma olen kirjutanud funktsiooni, mis on arvatavasti nimega JavaScript modalPopup mis võtab ühe parameetri. Ülaltoodud kommentaarides olen kasutanud phpDocumentori sarnast süntaksit, kus iga rea ​​eelneb a @ sümbol, millele järgneb valitud klahv. Need ei mõjuta teie koodi mingil moel, nii et saaksite kirjutada @description selle asemel @desc ilma muudatusteta.

Neid väikseid võtmeid kutsutakse tegelikult kommentaari sildid mis on veebisaidil suuresti dokumenteeritud. Võite vabalt teha oma enda ja kasutada neid nii, nagu soovid kogu oma koodi. Ma leian, et nad aitavad hoida kõike nii Võin lühidalt vaadata olulist teavet. Sa peaksid ka märkama, et olen seda kasutanud / * * / plokk-stiilis kommenteerimise formaat. See hoiab kõike palju puhtam kui topeltkalde lisamine, mis algab igal real.

Grupi / klassi kommentaarid

Lisaks funktsioonide ja silmuste kommenteerimisele ei kasutata ploki piirkondi nii sageli. Kus sa tõesti vajavad blokeeri kommentaarid on teie taustaprogrammide või raamatukogu failide juht. Iga veebisaidi iga faili kohta on lihtne minna välja ja kirjutada kindlat dokumentatsiooni - me näeme seda tava paljudes CMS-des, nagu näiteks WordPress.

Teie lehe ülemine ala peaks sisaldama kommentaare faili kohta. Nii saate kiiresti kontrollida, kus te redigeerite korraga töötades mitmel lehel. Lisaks saate seda ala kasutada ka andmebaasi kõige olulisemate funktsioonide kohta, mida vajate klassist välja.

/ ** * @desc sellel klassil on kasutaja interaktsiooni funktsioonid * näited on kasutaja_ülekanne (), kasutaja_kasutaja (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / abstraktne klass myWebClass  

Näete, et olen võltsimiseks kasutanud vaid väikest valimiklassi myWebClass kood. Olen lisanud mõned metainfo minu nime ja e-posti aadressiga kontakti saamiseks. Kui arendajad kirjutavad avatud lähtekoodi, on see üldiselt hea tava, nii et teised võivad sinuga abi saamiseks ühendust võtta. See on ka kindel meetod suuremates arendusmeeskondades töötamisel.

Märgis @nõutud pole midagi, mida ma olen mujal kasutanud. Olen mõnedes oma projektides vorminguga kursis olnud, ainult nendel lehekülgedel, kus olen palju meetodeid kohandanud. Kui lisate faile faile, peavad nad tulema enne koodi väljastamist. Seega on nende üksikasjade lisamine põhiklassi kommentaariplokkile hea viis pidage meeles, millised failid on vajalikud.

Front-endi koodi kommenteerimine

Nüüd, kui me oleme kaetud kolme olulise kommentaarimalliga, vaatame mõned teised näited. On palju frontendiarendajaid, kes on liikunud staatilisest HTML-st jQuery ja CSS koodiks. HTML-kommentaarid ei ole programmeerimisrakendustega võrreldes nii otstarbekad, kuid stiiliraamatukogude ja lehekülgede skriptide kirjutamise ajal võivad asjad aja jooksul segadusse saada.

JavaScript järgib tavapärasemat Java-, PHP- ja C / C-kommenteerimise meetodit++. CSS kasutab ainult plokk-stiilis kommentaare, mida piirab kaldkriips ja tärn. Peaksite meeles pidama, et kommentaarid kuvatakse teie külastajatele avalikult, sest ei CSS ega JS ei analüüsita serveripoolset, kuid üks neist meetoditest toimib suurepäraselt, et jätta oma koodis informatiivsed tidid tagasi minema.

Spetsiaalselt CSS-failide purustamine võib olla koristustöö. Me kõik teame, et jätta inline kommentaar Internet Exploreri või Safari paranduse selgitamiseks. Aga ma usun, et CSS-i kommenteerimist saab kasutada tasemel jQuery ja PHP neid kasutada. Lööme stiilirühmade loomiseks, enne kui puudutate mõningaid üksikasjalikke näpunäiteid koodi kommenteerimiseks.

CSS-i stiilirühmad

Neile, kes on CSS-i juba aastaid kujundanud, on see peaaegu teine ​​laad. Te mäletate aeglaselt kõiki omadusi, süntaksit ja ehitate oma süsteeme stiililehtedele. Oma töö kaudu olen loonud, mida ma kutsun rühmitamine siduda sarnased CSS-plokid üheks piirkonnaks.

CSS-i redigeerimisel tagasi pöördudes saan mõne sekundi pärast kergesti leida, mida ma vajan. See, kuidas otsustad stiilid grupeerida, on teie enda otsustada ja see on selle süsteemi ilu. Mul on mõned eelseadistatud standardid, mida ma allpool kirjeldan:

• @resets - vaikimisi brauseri marginaalide, polstrite, fontide, värvide jne eemaldamine.
• @fonts - lõiked, pealkirjad, blokkkoodid, lingid, kood
• @avigatsioon - peamised veebisaidi navigeerimislingid
• @layout - ümbris, konteiner, külgribad
• @header & @footer - need võivad erineda sõltuvalt teie disainist. Võimalikud stiilid hõlmavad linke ja järjestamata nimekirju, jaluse veerge, pealkirju, all-navi

Stiilide grupeerimisel olen leidnud märgistamissüsteem võib palju aidata. Kuid erinevalt PHP või JavaScript kasutan ühte @Grupp silt, millele järgneb kategooria või märksõnad. Olen lisanud 2 näidet allpool, et saaksite tunda, mida ma mõtlen.

/ ** @grupi jalus * / #footer styles…

/ ** @grupi jalus, väikesed fondid, veerud, välised lingid ** / 

Võite lisada iga kommentaaribloki juurde ka veidi lisateavet. Ma otsustan hoida asjad lihtsaks ja arusaadavaks stiilid on kergesti kooritavad. Kommenteerides on tegemist dokumentatsiooniga nii kaua, kui sa mõistad kirjalikult, et on hea minna!

4 nõuandeid paremate kommentaaride kujundamiseks

Me kulutasime selle artikli esimesel poolel erinevaid koodi kommenteerimise vorme. Arutagem nüüd mõningaid üldisi näpunäiteid, kuidas hoida teie koodi puhtana, organiseeritud ja kergesti mõistetavana.

1. Hoidke kõike loetavat

Mõnikord unustame seda arendajatena me kirjutame inimestele kommentaare lugemiseks. Kõik programmeerimiskeeled, mida me mõistame, on masinatele ehitatud, nii et see võib olla tüütu kirjutada tekstiks. On oluline märkida, et me ei ole siin, et kirjutada kolledži tasemel teadustöö, vaid lihtsalt lahkudes nõuandeid!

funktsiooni getTheMail () // code here ehitab e-posti / * run koodi, kui meie kohandatud sendMyMail () funktsiooni kõne tagastab tõelise leida sendMyMail () /libs/mailer.class.php, kontrollime, kas kasutaja täidab kõik väljad ja sõnum saadetakse! * / if (sendMyMail ()) tagasi tõsi; // hoida tõsi ja kuvada ekraanil edu

Isegi paar sõna on parem kui mitte midagi. Kui te lähete tagasi redigeerima ja töötate tulevikus projektidega, on sageli üllatav, kui palju unustate. Kuna te ei vaata iga päev samu muutujaid ja funktsiooninimesid, siis unustate enamuse oma koodist aeglaselt. Nii saate ei jäta kunagi liiga palju kommentaare! Kuid võite jätta liiga palju halbu kommentaare.

Üldine rusikareegel, võtke aega, et peatada ja mõelda enne kirjutamist. Küsi endalt mis on programmi jaoks kõige segasem ja kuidas seda kõige paremini selgitada “mannekeen” keel? Kaaluge ka miks sa kirjutad koodi täpselt nii, nagu sa oled.

Mõned kõige segadust tekitavad vead ilmuvad, kui unustate kohandatud ehitiste (või kolmanda osapoole) funktsioonide eesmärgi. Jäta kommentaarijälg tagasi mõne muu faili juurde kui see aitab teil funktsionaalsust kergemini meeles pidada.

2. Leevendage mõnda ruumi!

Ma ei saa piisavalt rõhutada, kui oluline tühik võib olla. See läheb kahekordselt tõsi PHP ja Ruby arendajatele, kes töötavad sadade failidega massilistel veebisaitidel. Sa vaatad seda koodi kogu päeva jooksul! Kas poleks tore, kui sa võiksid lihtsalt tähtsatesse piirkondadesse üle minna?

$ dir1 = "/ home /"; // seatud peamine kodu kataloog $ myCurrentDir = getCurDirr (); // seadistage praegune kasutaja kataloog $ userVar = $ get_username (); // praeguse kasutaja kasutajanimi

Ülaltoodud näites märkate iga rida kommentaaride ja koodi vahele paigutatud lisapadja. Failide sirvimisel on see kommenteerimisstiil selgelt välja paistma. See teeb vigade leidmise ja koodi parandamise sadu kordi lihtsamaks kui muutuvad plokid on nii puhas.

Sarnast ülesannet võiksite teha ka funktsiooni sees, kus sa segaduses, kuidas see toimib, kuid see meetod segaks teie koodi sisemise kommentaariga ja see on täpselt vastupidine korrektsele! Soovitan selles stsenaariumis loogilise piirkonna ümber suure plokk-rea kommentaar.

$ (dokument) .ready (funktsioon () $ ('. sub'). hide (); // peida sub-navigation pageload / ** kontrollige klikkimise sündmust ankrus sees .itm div takistage vaikelinki toiming, nii et leht ei muutu klõpsuga juurdepääsule .itm vanema elemendile, millele järgneb järgmine .sub nimekiri, et lülitada avatud / sulgeda ** / $ ('. itm a'). live ('kliki', funktsioon (e ) e.preventDefault (); $ (see) .parent () järgmine ('. sub'). slideToggle ('fast');););

See on väike jQuery kood, mis on suunatud alammenüü libistamisele. Esimene kommentaar on inline, et selgitada, miks me kõik peidame .alam klassid. Live-kliki sündmuste käitleja kohal olen kasutanud plokkide kommentaari ja kõik kirjalikult samasse punkti. See muudab asjad ilusamaks kui jooksvateks lõigeteks - eriti teistele, kes teie kommentaare lugevad.

3. Kommenteerige kodeerimise ajal

Koos õigete vahedega võib see olla üks parimaid harjumusi. Keegi ei taha oma programmi pärast tagasi minna ja iga tükk dokumenteerida. Enamik meist ei taha isegi minna tagasi ja dokumenteerida segadust tekitavaid valdkondi! See võtab tõesti palju tööd.

Aga kui te saate kodeerimise ajal kommentaare kirjutada kõik on teie meelest värske. Tavaliselt jäävad arendajad probleemi juurde ja veebi kergemini lahendada. Kui te tabate Eureka hetke ja lahendate sellise probleemi, on üldjuhul selge hetk, kus te mõistate oma varasemaid vigu. See oleks parim aeg jätke oma koodi kohta lahtised ja ausad kommentaarid.

Lisaks annab see teile praktika harjuda kõigi failide kommenteerimisega. Palju aega, mis on vajalik, et minna tagasi ja selgitada, kuidas midagi töötab, on palju suurem pärast funktsiooni ehitamist. Nii teie tulevane ise kui ka teie meeskonnakaaslased tänavad teid kommentaaride jätmise eest.

4. Bugiliste veadega tegelemine

Me ei saa kõik arvuti ees töötada tundide kirjutamiseks. Ma arvan, et saame proovida, kuid mingil hetkel peame magama! Tõenäoliselt peate oma koodi oma päeva jaoks osadeks jagama, mõned funktsioonid on ikka veel katki. Selle stsenaariumi puhul on oluline, et te jätke pikad ja üksikasjalikud kommentaarid selle kohta, kus sa asjad maha jätsid.

Isegi pärast värsket öö magamist võite olla üllatunud, kui keeruline on kodeerimise kiik tagasi saada. Näiteks kui te ehitate pildi üleslaadimise lehekülge ja peate selle lõpetamata jätma peaks kommenteerima, kuhu protsessi lahkusite. Kas pildid laaditakse ja salvestatakse temp-mälus? Või äkki ei ole neid üleslaadimisvormis isegi tunnustatud, või võib-olla nad ei ole pärast üleslaadimist leheküljel õigesti kuvatud.

Vigade kommenteerimine on oluline kahel peamisel põhjusel. Kõigepealt saate kergesti kiirenemist sealt, kus sa lahkusid ja Proovige probleemi (de) parandamiseks proovida uuesti värskelt. Ja teiseks saate eristada oma veebisaidi live-versiooni ja katsealuseid. Pea meeles, et kommentaare tuleks kasutada selgitage, miks sa midagi teed, mitte just seda, mida ta teeb.

Järeldus

Veebirakenduste ja tarkvara arendamine on täiuslik tava, ehkki raske. Kui olete üks vähestest arendajatest, kes tõesti mõistab ehitustarkvara, siis on oluline küpsustada oma kodeerimisoskustega. Kirjeldavate kommentaaride jätmine on pikaajaline lihtsalt hea tava, ja sa ei kaota seda kunagi!

Kui teil on ettepanekuid selgema koodi kommenteerimise kohta, siis andke meile teada allpool olevas arutelualal!