Šaltinio kodo komentarų stiliaus patarimai ir geriausios praktikos pavyzdžiai

Programuotojai, praleidę bet kokį laiką dideliuose projektuose, supranta kodų komentarų svarbą. Kai kuriate daug funkcijų į tą pačią programą, viskas yra sudėtinga. Yra tiek daug duomenų bitų, įskaitant funkcijas, kintamas nuorodas, grąžinimo reikšmes, parametrus ... kaip jūs tikitės išlaikyti?

Nenuostabu, kad jūsų kodo komentavimas yra labai svarbus, tiek solo, tiek komandų projektams. Tačiau daugelis kūrėjų nežino, kaip eiti šiuo procesu. Aš aprašiau kai kuriuos savo asmeninius gudrybės sukurti tvarkingus, suformatuotus kodo komentarus. Standartai ir komentarų šablonai skirtingiems kūrėjams skirsis, bet galiausiai turėtumėte siekti švarios ir skaitomos pastabos toliau paaiškinti klaidinančias jūsų kodo sritis.

Turėtume pradėti aptarti kai kuriuos komentarų formatavimo skirtumus. Tai suteiks jums geresnį supratimą apie tai, kaip išsamiai galite susipažinti su projekto kodu. Vėliau pasiūlysiu konkrečių patarimų ir pavyzdžių, kuriuos galite pradėti naudoti iš karto!

Komentarų stiliai: apžvalga

Pažymėtina, kad šios idėjos yra tik Gairės link švaresnių komentarų. Individualios programavimo kalbos nenurodo gairių ar specifikacijų, kaip nustatyti dokumentaciją.

Be to, šiuolaikiniai kūrėjai sugrupavo, kad formuotų savo kodų komentavimo sistemą. Aš siūlysiu keletą pagrindinių stilių ir išsamiai paaiškinsiu jų paskirtį.

Komentuoti komentarus

Praktiškai kiekviena programavimo kalba siūlo komentarai. Tai yra tik vienos eilutės turinys ir komentuoja tekstą tik po tam tikro momento. Taigi, pvz., C / C ++ pradžioje pradėsite tokį komentarą:

// pradėti kintamąjį sąrašą var myvar = 1; 

Tai puikiai tinka kelis sekundes į kodą paaiškinti galbūt painią funkciją. Jei dirbate su daugeliu parametrų ar funkcijų skambučių, netoliese galite įdėti daug pastovių komentarų. Tačiau naudingiausias naudojimas yra a paprastas mažo funkcionalumo paaiškinimas.

jei (callAjax ($ params)) // sėkmingai paleisti callAjax su vartotojo parametrais ... kodas

Visų pirma, po kodo atidarymo, kodas turėtų būti naujoje eilutėje. Priešingu atveju visa tai būtų sugauta toje pačioje komentarų eilutėje! Venkite važiuoti už borto nes paprastai nereikia matyti vieno eilutės komentarų iki galo žemyn savo puslapio, bet ypač dėl painiavos, esančios jūsų kodo, tai yra daug lengviau atsisakyti paskutinės minutės.

Aprašomieji blokai

Kai reikia įtraukti didelį paaiškinimą, paprastai vienas laineris nepadės. Kiekvienoje programavimo srityje yra iš anksto suformatuoti komentarų šablonai. Aprašomieji blokai labiausiai matomi aplink funkcijas ir bibliotekos failus. Kai nustatysite naują funkciją, tai yra gera praktika virš deklaracijos pridėkite aprašomąjį bloką.

/ ** * @desc atidaro modalinį langą, kad būtų rodomas pranešimas * @param string $ msg - rodomas pranešimas * @return bool - sėkmė arba gedimas * / funkcija modalPopup ($ msg) … 

Aukščiau yra paprastas aprašomojo funkcijų komentaro pavyzdys. Aš parašiau funkciją, kuri tikriausiai vadinama „JavaScript“ modalPopup kuris turi vieną parametrą. Pirmiau pateiktose pastabose naudoju sintaksę, panašią į phpDocumentor, kur prieš kiekvieną eilutę yra a @ simbolis ir pasirinktas raktas. Tai neturės įtakos jūsų kodui jokiu būdu, kad galėtumėte rašyti @apibūdinimas vietoj @desc be jokių pakeitimų.

Šie maži raktai yra iš tikrųjų vadinami komentarų žymas kurie yra smarkiai dokumentuojami svetainėje. Nesivaržykite užpildyti savo ir naudoti šiuos kodus, kaip norite. Manau, kad jie padeda išlaikyti viską, kas taip teka Iš pirmo žvilgsnio galiu patikrinti svarbią informaciją. Taip pat turėtumėte pastebėti, kad aš naudoju / * * / blokinio stiliaus komentavimo formatas. Tai bus viskas daug švaresnis nei pridedant dvigubą brūkšnį, pradedant nuo kiekvienos.

Grupės / klasės komentarai

Be funkcijų ir kilpų komentavimo, blokų sritys nėra naudojamos taip dažnai. Kur jums tikrai reikia stiprios blokuoti komentarus yra jūsų „backend“ dokumentų ar bibliotekos failų galva. Tai lengva eiti visur ir rašyti tvirtą dokumentaciją kiekvienam failui jūsų svetainėje - šią praktiką matome daugelyje TVS, pvz., „WordPress“.

Pačioje puslapio viršuje turėtų būti pastabų dėl paties failo. Tokiu būdu jūs galite greitai patikrinkite, kur redaguojate tuo pačiu metu dirbant keliuose puslapiuose. Be to, galite naudoti šią sritį kaip svarbiausių funkcijų, kurių jums reikia, duomenų bazę iš klasės.

/ ** * @desc ši klasė turės funkcijų, skirtų vartotojo sąveikai * pavyzdžiai: user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * abstrakta klasė myWebClass  

Jūs galite pamatyti, kad aš naudoju tik nedidelę mėginių klasę suklastotai myWebClass kodą. Pridėjau kai kurios meta informacijos su mano vardu ir el. pašto adresu. Kai kūrėjai rašo atviro kodo kodą, tai paprastai yra gera praktika, todėl kiti gali susisiekti su jumis dėl palaikymo. Tai taip pat yra tvirtas metodas dirbant didesnėse plėtros komandose.

Žyma @privaloma nėra kažkas, ką mačiau kitur. Aš palaikiau formą keliuose mano projektuose, tik puslapiuose, kuriuose pritaikiau daug metodų. Kai įtraukiate puslapius į failą, jie turi ateiti prieš pateikdami bet kokį kodą. Taigi pridedant šiuos duomenis į pagrindinės klasės komentarų bloką, tai yra geras būdas prisiminkite, kuriuos failus reikia.

Komentuoti „Front-end Code“

Dabar, kai aptarėme 3 svarbius komentarų šablonus, pažvelkime į keletą kitų pavyzdžių. Yra daug „frontend“ kūrėjų, kurie perėjo iš statinio HTML į jQuery ir CSS kodą. HTML komentarai nėra tokie tikslingi, kaip ir programavimo programose, bet kai rašote stiliaus bibliotekas ir puslapių scenarijus, laikui bėgant dalykai gali būti nepatogūs.

„JavaScript“ laikosi tradicinio metodo, panašaus į „Java“, „PHP“ ir „C / C“++. CSS naudoja tik bloko stiliaus komentarus, apibrėžtus brūkšniu ir žvaigždute. Turėtumėte nepamiršti, kad komentarai bus atidžiai rodomi jūsų lankytojams, nes nei CSS, nei JS neišnagrinėja serverio pusės, tačiau bet kuris iš šių metodų puikiai tinka paliekant informatyvius tidbitus į kodą, kad grįžtumėte atgal.

Konkrečiai CSS failai gali būti sutvarkyti. Visi žinome, kad paliekame eilinį komentarą, kad paaiškintumėte „Internet Explorer“ arba „Safari“ pataisą. Bet manau, kad CSS komentavimas gali būti naudojamas jQuery ir PHP naudojimui. Prieš paliesdami keletą išsamių patarimų kodų komentavimui, įsikursime į stiliaus grupes.

CSS stiliaus grupės

Tiems, kurie jau daugelį metų projektuoja CSS, jis beveik yra antras. Lėtai įsiminti visas savybes, sintaksę ir sukurti savo stilių lentelės sistemą. Savo darbe sukūriau tai, ką vadinu grupavimas sujungti panašius CSS blokus į vieną sritį.

Grįžus prie redagavimo CSS, per kelias sekundes galiu lengvai rasti tai, ko man reikia. Tai, kaip pasirinksite grupuoti stilius, priklauso tik nuo jūsų, ir tai yra šios sistemos grožis. Turiu kelis iš anksto nustatytus standartus, kuriuos išdėstiau toliau:

• @resets - nuimant numatytasis naršyklės paraštes, padding, šriftus, spalvas ir kt.
• @fonts - pastraipos, antraštės, bloknotai, nuorodos, kodas
• @navigation - pagrindinės pagrindinės svetainės navigacijos nuorodos
• @layout - įvynioklis, konteineris, šoninės juostos
• @header & @footer - tai gali skirtis priklausomai nuo jūsų dizaino. Galimi stiliai apima nuorodas ir neregistruotus sąrašus, poraštės stulpelius, antraštes, sub-navus

Grupuojant stilių lenteles radau žymėjimo sistema gali daug padėti. Tačiau, skirtingai nei PHP ar JavaScript, naudoju vieną @group žyma, po kurios yra kategorija arba raktiniai žodžiai. Toliau pateikiau 2 pavyzdžius, kad galėtumėte jaustis, ką aš turiu galvoje.

/ ** @group footer * / #footer stiliai…

/ ** @ grupių poraštė, maži šriftai, stulpeliai, išorinės nuorodos ** / 

Taip pat kiekviename komentarų bloke galite pridėti šiek tiek papildomos informacijos. Aš pasirinkau išlaikyti dalykus paprastus ir paprastus todėl stilių lentelės yra lengvai nugriebtos. Komentavimas yra susijęs su dokumentacija, kol jūs suprantate, kad rašyti tai gerai!

4 patarimai, kaip geriau komentuoti stilių

Pirmąjį šio straipsnio pusmetį praleidome ieškodami įvairių kodų komentavimo formatų. Dabar aptarkime keletą bendrų patarimų, kaip išlaikyti kodą švariu, organizuotu ir lengvai suprantamu.

1. Laikykite viską skaitymą

Kartais kaip kūrėjai tai užmirštame rašome komentarus žmonėms skaityti. Visos programavimo kalbos, kurias mes suprantame, yra sukurtos mašinoms, todėl gali būti sunku konvertuoti į paprastą rašytinį tekstą. Svarbu pažymėti, kad čia nėra rašyti kolegijos lygio tyrimą, bet tiesiog paliekant patarimus!

funkcija getTheMail () // kodas čia bus pastatytas el. paštas / * paleisti kodą, jei mūsų priskirtas sendMyMail () funkcijos skambutis grąžins teisingą rasti sendMyMail () į /libs/mailer.class.php mes tikriname, ar vartotojas užpildo visus laukus ir pranešimas išsiųstas! * / if (sendMyMail ()) grįžti tiesa; // išlaikyti teisingą ir rodyti ekrano sėkmę

Net tik keli žodžiai geriau negu nieko. Kai grįšite prie redagavimo ir dirbate su projektais ateityje, tai dažnai stebina, kiek pamiršti. Kadangi jūs nežiūrite į tuos pačius kintamuosius ir funkcijų pavadinimus kiekvieną dieną, jūs linkę lėtai pamiršti didžiąją savo kodo dalį. Taip galite niekada nepalikite per daug komentarų! Tačiau galite palikti per daug blogų komentarų.

Kaip bendra nykščio taisyklė, prireiks šiek tiek laiko sustabdyti ir atspindėti prieš rašydami. Paklausk savęs kas yra painiausia dėl programos ir kaip galėtumėte geriausiai tai paaiškinti “manekenas” kalba? Taip pat apsvarstykite kodėl jūs rašote kodą tiksliai taip, kaip jūs.

Kai kurios iš labiausiai klaidinančių klaidų pasirodo, kai pamiršote pagal užsakymą pastatytų (arba trečiųjų šalių) funkcijų paskirtį. Palikite komentarų taką atgal į keletą kitų failų jei tai padės lengviau prisiminti funkcionalumą.

2. Mažinti tam tikrą erdvę!

Aš negaliu pakankamai pabrėžti, kaip svarbu balta vieta gali būti. Tai vyksta dvigubai tiesa PHP ir Ruby programuotojams, kurie dirba su didžiulėmis svetainėmis, kuriose yra šimtai failų. Jūs visą laiką žiūrėsite į šį kodą! Ar ne būtų puiku, jei galėtumėte tiesiog pasinerti į svarbias sritis?

$ dir1 = "/ home /"; // nustatyti pagrindinį namų katalogą $ myCurrentDir = getCurDirr (); // nustatyti dabartinį vartotojo katalogą $ userVar = $ get_username (); // dabartinio vartotojo naudotojo vardas

Pirmiau pateiktame pavyzdyje pastebėsite, kad kiekvienoje eilutėje yra papildomų pagalvėlių, kurias aš įdėjau tarp komentarų ir kodo. Slenkant per failus, šis komentavimo būdas bus aiškiai išsiskiria. Tai padeda rasti klaidų ir pataisyti kodą šimtus kartų lengviau kai kintamieji blokai yra tokie švarus.

Jūs galite atlikti panašią užduotį kodo viduje funkcijos viduje, kur jūs supainiotumėte, kaip jis veikia, tačiau šis metodas galiausiai netrukdytų jūsų kodui su įterptais komentarais, ir tai yra visiškai priešingas tvarkingai! Šį scenarijų rekomenduoju pridedant didelį blokinės eilutės komentarą apie logikos sritį.

$ (dokumentas). jau (funkcija () $ ('. sub'). paslėpti (); // paslėpti sub-navigaciją dėl pageload / ** paspaudimo įvykio patikrinimo ankeryje .itm div užkirsti kelią numatytąją nuorodą veiksmas, kad puslapis nepasikeistų paspaudus prieigą prie pagrindinio „.itm“ elemento, po kurio sekamas .sub sąrašas, kad perjungtumėte atidarymą / uždarymą ** / $ („. itm a“). gyventi („spustelėkite“, funkcija (e ) e.preventDefault (); $ (this) .parent (). Kitas ('. sub'). slideToggle ('fast');););

Tai nedidelis „jQuery“ kodo, nukreipiančio į posmenio slankiąją navigaciją, šiek tiek. Pirmoji pastaba yra aiški, kodėl mes slepiame visus .sub klasės. Virš realaus paspaudimo įvykių tvarkytojo naudoju blokinį komentarą ir į tą patį tašką įtraukė visus raštu. Tai daro viską gražiau, o ne paleidžiamas dalis - ypač tiems, kurie skaito jūsų komentarus.

3. Komentuoti koduojant

Kartu su tinkamu atstumu tai gali būti vienas iš geriausių įpročių. Niekas nenori grįžti per savo programą po to, kai jis dirba ir dokumentuoja kiekvieną kūrinį. Daugelis iš mūsų net nenori grįžti ir supainioti painias sritis! Tai iš tikrųjų užima daug darbo.

Bet jei galite užrašyti komentarus koduodami viskas vis dar bus šviežia jūsų prote. Paprastai kūrėjai įstrigs prie problemos ir paprasčiausiai išsivalys internetą. Paspaudus „Eureka“ momentą ir išsprendus tokią problemą, paprastai būna aiškumo momentas, kur suprantate ankstesnes klaidas. Tai būtų geriausias laikas palikti atvirus ir sąžiningus komentarus apie jūsų kodą.

Be to, tai padės jums priprasti prie visų jūsų failų komentavimo. Kiek laiko reikia grįžti ir išsiaiškinti, kaip kažkas veikia, yra daug didesnė po to, kai jau sukūrėte šią funkciją. Ateities savęs ir jūsų komandos nariai padėkos jums už tai, kad palikote komentarus anksčiau.

4. Spręsti klaidas

Mes negalime visi sėdėti prie kompiuterio valandų rašymo kodo. Manau, mes galime pabandyti, bet tam tikru momentu turime miegoti! Tikriausiai turėsite dalytis keliais būdais su savo kodu tam tikroms funkcijoms, kurios vis dar neveikia. Šiuo atveju labai svarbu, kad jūs palikite ilgas, išsamias pastabas apie tai, kur jūs palikote dalykus.

Net po šviežios nakties miego jums gali būti nustebintas tuo, kaip sunku grįžti į kodavimo svyravimą. Pavyzdžiui, jei statote vaizdo įkėlimo puslapį ir turite jį palikti nebaigtą, jūs turėtų pakomentuoti, kur vyko procesas. Ar vaizdai įkeliami ir saugomi atmintyje? O gal jie netgi nepripažįstami įkėlimo formoje, o gal jie nėra tinkamai rodomi puslapyje po įkėlimo.

Klaidų komentavimas yra svarbus dėl dviejų pagrindinių priežasčių. Pirmiausia galite lengvai pasiimkite ten, kur išėjote ir pabandykite dar kartą atnaujinti problemą (-as). Ir, antra, galite atskirti gyvos gamybos svetainės versiją ir testavimo vietas. Atminkite, kad komentarai turėtų būti naudojami paaiškinkite, kodėl jūs darote kažką, ne tai, ką ji daro.

Išvada

Žiniatinklio programų ir programinės įrangos kūrimas yra tinkama praktika, nors ir sudėtinga. Jei esate vienas iš nedaugelio kūrėjų, kurie iš tikrųjų supranta pastato programinę įrangą, svarbu suburti savo kodavimo įgūdžius. Palikti aprašomuosius komentarus yra tik geroji patirtis ilgainiui, ir jūs tikriausiai niekada nesigailėsite!

Jei turite pasiūlymų dėl aiškesnio kodo komentavimo, leiskite mums pranešti toliau pateikiamoje diskusijų srityje!