Nasveti za oblikovanje stila za kodo izvorne kode in najboljše prakse

Razvijalci, ki so preživeli nekaj časa na velikih projektih, razumejo pomen komentarjev kode. Ko v isto aplikacijo gradite številne funkcije, se stvari zapletajo. Obstaja toliko podatkovnih bitov, vključno s funkcijami, referencami spremenljivk, vrnjenimi vrednostmi, parametri ... kako se pričakuje, da boste sledili?

Ni presenetljivo, da je komentiranje vaše kode bistvenega pomena, tako solo kot ekipni projekti. Toda mnogi razvijalci se ne zavedajo, kako se lotiti tega procesa. Omenil sem nekaj svojih osebnih trikov ustvarjanje urejenih, oblikovanih komentarjev kode. Standardi in predloge komentarjev se bodo razlikovali med razvijalci - vendar si morate končno prizadevati čiste in berljive pripombe da bi dodatno pojasnili zmedena področja v vaši kodi.

Začeti bi morali razpravljati o nekaterih razlikah v oblikovanju komentarjev. To vam bo dalo boljšo predstavo o tem, kako podrobno lahko postanete s kodo projekta. Nato vam bom ponudil nekaj posebnih nasvetov in primerov, ki jih lahko takoj začnete uporabljati!

Slogi komentarjev: Pregled

Opozoriti je treba, da so predstavljene ideje samo smernice čistejše pripombe. Posamezni programski jeziki ne določajo smernic ali specifikacij za nastavitev dokumentacije.

Kljub temu so se sodobni razvijalci združili in oblikovali svoj sistem komentiranja kode. Ponudil bom nekaj mainstream stilov in se pogovoril o njihovem namenu.

Vstavljanje komentarjev

Praktično vsak posamezen programski jezik ponuja inline komentarji. Te so omejene na vsebino z eno vrstico in besedilo komentirajo samo po določeni točki. Tako na primer v C / C ++ začnete kot vnesti komentar:

// začetek uvrstitve spremenljivke var myvar = 1;… 

To je idealno za klicanje v kodo za nekaj sekund pojasnite morebitno zmedo. Če delate z veliko parametri ali funkcijskimi klici, lahko v bližini postavite številne komentarje. Toda najbolj koristna uporaba je enostavna razlaga za majhne funkcionalnosti.

if (callAjax ($ params)) // uspešno zažene callAjax z uporabniškimi parametri ... koda

Opozorilo predvsem, da bi morala biti koda v novi vrstici po začetni oklepaju. V nasprotnem primeru bi se vse ujelo na isto linijo komentarjev! Izogibajte se pretiravanju ker na vaši strani ponavadi ni treba prikazati komentarjev v eni vrstici, še posebej za zmedeno križanje v kodi, je to veliko lažje v zadnjem trenutku.

Opisni bloki

Ko morate vključiti veliko razlago, običajno en liner ne bo naredil trika. Obstajajo vnaprej oblikovane predloge komentarjev, ki se uporabljajo na vseh področjih programiranja. Opisni bloki najbolj opazne funkcije in knjižnične datoteke. Kadarkoli nastavite novo funkcijo, je dobra praksa nad deklaracijo dodajte opisni blok.

/ ** * @desc odpre modalno okno za prikaz sporočila * @param string $ msg - sporočilo, ki se prikaže * @return bool - uspeh ali neuspeh * / funkcija modalPopup ($ msg) … 

Zgoraj je preprost primer opisne funkcije komentarja. Napisal sem funkcijo, ki naj bi jo klical JavaScript modalPopup ki ima en sam parameter. V zgornjih komentarjih sem uporabil skladnjo, podobno phpDocumentor, kjer je pred vsako vrstico pred @ simbol, ki mu sledi izbrana tipka. To nikakor ne bo vplivalo na vašo kodo, tako da lahko pišete @opis namesto @desc brez sprememb.

Ti majhni ključi se dejansko kličejo oznake komentarjev ki so močno dokumentirani na spletni strani. Izdelajte si lastne in jih uporabljajte po svoji želji v svoji kodi. Ugotavljam, da pomagajo ohraniti vse to tako Na kratko lahko preverim pomembne informacije. Prav tako morate opaziti, da sem uporabil / * * / format komentiranja blokovnega sloga. To bo obdržalo vse veliko čistejše kot dodajanje dvojne poševnice, ki se začne pri vsaki vrstici.

Komentarji skupine / razreda

Poleg komentiranja funkcij in zank se območja blokov ne uporabljajo tako pogosto. Kje res potrebujete močno blokirajte komentarje so na vrhu vaših hrbtnih dokumentov ali knjižničnih datotek. Za vsako datoteko na vaši spletni strani je preprosto izčrpati in napisati trdno dokumentacijo - to prakso lahko vidimo v številnih CMS, kot je WordPress.

Zgornji del vaše strani mora vsebovati komentarje glede same datoteke. Na ta način lahko hitro preverite, kam urejate na več straneh hkrati. To področje lahko uporabite tudi kot bazo podatkov za najpomembnejše funkcije, ki jih potrebujete izven razreda.

/ ** * @desc ta razred bo imel funkcije za uporabniško interakcijo * primeri vključujejo user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / abstraktni razred myWebClass  

Vidite, da sem uporabil le majhen vzorec za ponaredek myWebClass Koda. Dodal sem nekaj meta informacij z imenom in e-poštnim naslovom za stik. Ko razvijalci pišejo odprto kodo, je to na splošno dobra praksa, da se lahko drugi obrnete na vas za podporo. To je tudi trdna metoda pri delu v večjih razvojnih timih.

Oznaka @required nisem videl drugje. Oblikoval sem v nekaj svojih projektih, samo na straneh, kjer sem prilagodil veliko metod. Kadarkoli vključite strani v datoteko, morajo priti, preden odprete kodo. Torej je dodajanje teh podrobnosti v glavni blok komentarjev razreda dober način ne pozabite, katere datoteke so potrebne.

Front-end komentiranje kode

Zdaj, ko smo zajeli 3 pomembne predloge komentarjev, si poglejmo še nekaj drugih primerov. Obstaja veliko razvijalcev frontendov, ki so se preselili iz statičnega HTML-ja v jQuery in CSS kodo. Komentarji HTML niso tako smiselni v primerjavi s programskimi aplikacijami, ko pa pišete stilske knjižnice in skripte strani, lahko stvari sčasoma postanejo neurejene.

JavaScript sledi bolj tradicionalni metodi komentiranja, podobno Java, PHP in C / C++. CSS uporablja samo komentarje sloga bloka, ki so označeni s poševnico in zvezdico. Ne pozabite, da bodo komentarji odprti za vaše obiskovalce, saj niti CSS niti JS niso razčlenjeni na strani strežnika, vendar je vsaka od teh metod odlična za prepuščanje informativnih posnetkov v kodo, da se vrnejo nazaj.

Zlasti razstavljanje CSS datotek je lahko opravilo. Vsi smo seznanjeni s tem, da zapustimo inline komentar, ki pojasnjuje popravke za Internet Explorer ali Safari. Ampak verjamem, da lahko CSS komentiranje uporabljate na ravni jQuery in PHP jih uporabljata. Potem se poglobimo v ustvarjanje skupin slogov, preden se dotaknemo nekaterih podrobnih nasvetov za komentiranje kode.

Skupine slogov CSS

Za tiste, ki že vrsto let oblikujejo CSS, je to skoraj druga narava. Počasi si zapomniš vse lastnosti, skladnjo in zgradiš svoj sistem za sloge. S svojim delom sem ustvaril, kar kličem združevanje združiti podobne bloke CSS na eno področje.

Ko se vrnemo k urejanju CSS, lahko v nekaj sekundah zlahka najdem, kar potrebujem. Način, ki ga izberete za združevanje slogov, je v celoti odvisen od vas, in to je lepota tega sistema. Imam nekaj prednastavljenih standardov, ki sem jih opisal spodaj:

• @resets - odvzemanje privzetih robov brskalnika, oblazinjenje, pisave, barve itd.
• @fonts - odstavki, naslovi, blockquotes, povezave, koda
• @ navigacija - glavne jedrne povezave za navigacijo na spletni strani
• @layout - ovoj, posodo, stranske trakove
• @header & @footer - to se lahko razlikuje glede na vašo obliko. Možni slogovi vključujejo povezave in neurejene sezname, stolpce za noge, naslove, podprograme

Ko združujete sloge, sem našel sistem označevanja lahko veliko pomaga. Vendar pa za razliko od PHP ali JavaScript uporabljam eno @group sledi kategorija ali ključne besede. V nadaljevanju sem navedla dva primera, tako da lahko dobite občutek za to, kar mislim.

/ ** @group footer * / #footer styles…

/ ** @group footer, majhne pisave, stolpci, zunanje povezave ** / 

Alternativno lahko dodate nekaj dodatnih podrobnosti v vsakokratni blok komentarjev. Odločil sem se poskrbite, da bodo stvari preproste in enostavne tako, da so slogi preprosto posnemati. Komentiranje je vse o dokumentaciji, dokler razumete pisanje, je dobro iti!

4 Nasveti za boljše oblikovanje komentarjev

V prvi polovici tega članka smo preučili različne formate za komentiranje kode. Oglejmo si nekaj splošnih nasvetov, kako ohraniti kodo čisto, organizirano in lahko razumljivo.

1. Hranite vse berljivo

Včasih kot razvijalci to pozabljamo pišemo komentarje za branje ljudi. Vsi programski jeziki, ki jih razumemo, so zgrajeni za stroje, zato je lahko dolgočasno pretvarjati se v navadno pisno besedilo. Pomembno je omeniti, da nismo tukaj, da bi napisali raziskovalni papir na ravni kolegija, ampak samo puščam napitke!

funkcija getTheMail () // koda tukaj bo zgradila e-pošto / * zagonsko kodo, če bo naš klic po meri sendMyMail () vrnil true najdi sendMyMail () v /libs/mailer.class.php preverjamo, če uporabnik izpolni vsa polja in sporočilo je poslano! * / if (sendMyMail ()) return true; // ostane resničen in prikaže uspeh na zaslonu

Celo samo nekaj besed je boljše kot nič. Ko se v prihodnosti vrnete na urejanje in delo na projektih, je pogosto presenetljivo, koliko boste pozabili. Ker ne iščete enakih spremenljivk in funkcijskih imen, vsak dan ponavadi pozabite večino kode. Tako lahko nikoli ne pustite preveč komentarjev! Vendar lahko pustite preveč slabih komentarjev.

Kot splošno pravilo, vzemite si nekaj časa, da se ustavite in razmislite pred pisanjem. Vprašaj se kar je najbolj zmedeno glede programa in kako lahko najbolje razložite “lutke” jezik? Upoštevajte tudi zakaj pišete kodo točno tako kot ste.

Nekatere najbolj zmedene napake se pojavijo, ko pozabite na namen prilagojenih funkcij (ali tretjih oseb). Pustite komentar, ki vodi nazaj do nekaj drugih datotek če vam bo to pomagalo, da si lažje zapomnite funkcionalnost.

2. Olajšajte nekaj prostora!

Ne morem dovolj poudariti, kako pomembno je presledek je lahko. To gre dvakrat res za razvijalce PHP in Ruby, ki delajo na velikih spletnih mestih s stotinami datotek. Ves ta dan boste gledali v to kodo! Ali ne bi bilo super, če bi lahko samo preletel do pomembnih območij?

$ dir1 = "/ home /"; // nastavite glavni domači imenik $ myCurrentDir = getCurDirr (); // nastavimo trenutni uporabniški imenik $ userVar = $ get_username (); // uporabniško ime trenutnega uporabnika

V zgornjem primeru boste opazili dodatno oblazinjenje, ki sem ga postavil med komentarji in kodo v vsaki vrstici. Ko se pomikate po datotekah, bo ta stil komentiranja jasno izstopajo. To omogoča stotine krat lažje iskanje napak in popravljanje kode kadar so spremenljivi bloki tako čist.

Podobno nalogo lahko opravite na kodi znotraj funkcije, kjer ste zmedeni o tem, kako deluje, toda ta metoda bi sčasoma zakrčila vašo kodo z vstavljenimi komentarji in to je ravno nasprotno od pravilnega! Priporočam v tem scenariju dodajanje velikega blokovnega komentarja na področju logike.

$ (document) .ready (function () $ ('. sub'). hide (); // skrij pod-navigacijo na pageload / ** preverite za dogodek klika na sidru znotraj .itm div preprečite privzeto povezavo Dejanje, tako da se stran ne spremeni ob dostopu s klikom na starševski element .itm, ki mu sledi naslednji seznam .sub, da preklopite na odprto / zaprto ** / $ ('. itm a'). live ('klik', funkcija (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('hitro');););

To je majhen del kode jQuery, ki cilja na podmeni z drsno navigacijo. Prvi komentar je pojasnjen, zakaj skrivamo vse .sub razredi. Nad obdelovalcem dogodkov za klikanje v živo sem uporabil blok komentar in vsa pisava je vstavljena v isto točko. To pomeni, da so stvari lepše, namesto da se izvajajo odstavki - še posebej za druge, ki berejo vaše komentarje.

3. Komentar med kodiranjem

Skupaj z ustreznim razmikom je to lahko ena od najboljših navad, v katere lahko vstopite. Nihče se ne želi vrniti po svojem programu, ko dela in dokumentira vsak kos. Večina od nas sploh ne želi iti nazaj in dokumentirati zmedenih področij! Zares potrebuje veliko dela.

Ampak, če lahko napišete komentarje, medtem ko kodirate vse bo še vedno sveže v tvoji glavi. Običajno se bodo razvijalci zaljubili v težavo in preiskali splet za najlažjo rešitev. Ko zadeneš trenutek Eureke in rešiš takšen problem, je navadno trenutek v jasnosti, ko razumeš prejšnje napake. To bi bilo najboljši čas pustiti odprte in poštene pripombe o vaši kodi.

Poleg tega se boste lahko navadili na komentiranje vseh datotek. Koliko časa potrebujete, da se vrnete nazaj in ugotovite, kako nekaj deluje, je veliko več, potem ko ste že zgradili funkcijo. Tako vaša bodoča jaz, kot tudi vaši sodelavci vam bodo hvaležni, da ste predčasno oddali komentarje.

4. Ukvarjanje z napakami v buggyju

Ne moremo vsi sedeti pred računalnikom več ur, ko pišejo kodo. Mislim, da lahko poskusimo, toda na neki točki moramo spati! Verjetno boste morali deliti poti s svojo kodo za dan, medtem ko so nekatere funkcije še vedno pokvarjene. V tem scenariju je ključnega pomena, da vas pustite dolge, podrobne komentarje o tem, kje ste pustili stvari.

Tudi po svežem nočnem spanju boste morda presenečeni, kako težko se lahko vrnete v nihanje kodiranja. Na primer, če gradite stran za nalaganje slik in jo morate zapustiti nedokončano, boste bi morali komentirati, kje v postopku ste končali. Ali se slike nalagajo in shranjujejo v pomnilniku temp? Ali pa morda sploh niso priznani v obrazcu za nalaganje ali pa morda niso pravilno prikazani na strani po nalaganju.

Napake pri komentiranju so pomembne iz dveh glavnih razlogov. Najprej lahko preprosto poberete tam, kjer ste končali in poskusite znova sveže, da odpravite težavo ali težave. In drugič, lahko razlikovati med produkcijsko različico vašega spletnega mesta in preizkusnimi polji. Ne pozabite, da je treba uporabiti komentarje pojasnite, zakaj nekaj delate, ni ravno to, kar počne.

Zaključek

Razvoj spletnih aplikacij in programske opreme je izpolnjen, čeprav težaven. Če ste eden redkih razvijalcev, ki resnično razume gradnjo programske opreme, potem je pomembno, da z zornimi veščinami zorete. Če opišemo opisne komentarje, je to le dobra praksa na dolgi rok, in verjetno vam nikoli ne bo žal!

Če imate predloge za jasnejše komentiranje kode, nam to sporočite v razpravi spodaj!