Izvorni kod Savjeti za oblikovanje stila i najbolje prakse

Programeri koji su proveli neko vrijeme na velikim projektima razumiju važnost komentara koda. Kada gradite mnoge značajke u istoj aplikaciji, stvari postaju komplicirane. Postoji toliko mnogo bitova podataka, uključujući funkcije, reference varijabli, povratne vrijednosti, parametre ... kako se očekujete da ćete nastaviti pratiti?

Ne treba čuditi da je komentiranje vašeg koda ključno, i solo i timski projekti. No, mnogi programeri nisu svjesni kako to učiniti. Opisao sam neke svoje osobne trikove stvaranje urednih, oblikovanih komentara komentara. Standardi i predlošci komentara razlikuju se među programerima - ali u konačnici trebate težiti čisti i čitljivi komentari kako bi dodatno objasnili zbunjujuća područja u vašem kodu.

Trebali bismo početi raspravljati o nekim razlikama u oblikovanju komentara. To će vam dati bolju predodžbu o tome koliko detaljno možete postati s kodom projekta. Nakon toga ponudit ću vam neke specifične savjete i primjere koje možete odmah početi koristiti!

Stilovi komentara: Pregled

Treba napomenuti da su ove ideje samo predstavljene smjernice prema čistijim komentarima. Pojedinačni programski jezici ne postavljaju smjernice ili specifikacije za postavljanje vaše dokumentacije.

S obzirom na to, suvremeni programeri grupirali su se kako bi oblikovali vlastiti sustav komentiranja koda. Ponudit ću nekoliko mainstream stilova i otići u detalje njihove namjene.

Inline Commenting

Praktično svaki pojedini programski jezik nudi ugrađeni komentari. One su ograničene na jedan redak i komentiraju tek nakon određene točke. Tako na primjer u C / C ++ započinjete inline komentar poput ovog:

// započinje unos varijable var myvar = 1;… 

To je savršeno za zvonjenje u kodu na nekoliko sekundi objasnite eventualno zbunjujuću funkcionalnost. Ako radite s mnogo parametara ili pozivima na funkcije, u blizini možete postaviti niz umetnutih komentara. Ali najkorisnija je upotreba jednostavna objašnjenja za male funkcionalnosti.

if (callAjax ($ params)) // uspješno je pokrenuo callAjax s korisničkim parametrima… kod

Primijetite da bi prije svega kôd trebao biti na novoj liniji nakon otvaranja zagrade. Inače bi sve bilo uhvaćeno na istoj liniji komentara! Izbjegavajte pretjerivanje budući da općenito ne morate vidjeti jednostruke komentare sve do vaše stranice, ali posebno za zbunjujuće spojeve u kodu, to je mnogo lakše ispustiti u zadnjoj minuti.

Opisni blokovi

Kada trebate uključiti veliko objašnjenje općenito jedan linijski brod neće uspjeti. Postoje predformatirani obrasci komentara koji se koriste u svakom području programiranja. Opisni blokovi najčešće se vide oko funkcija i knjižničnih datoteka. Kada postavite novu funkciju, to je dobra praksa dodajte opisni blok iznad deklaracije.

/ ** * @desc otvara modalni prozor za prikaz poruke * @param string $ msg - poruka koja se prikazuje * @return bool - uspjeh ili neuspjeh * / funkcija modalPopup ($ msg) … 

Gore je jednostavan primjer opisne funkcije funkcije. Napisao sam funkciju vjerojatno u JavaScript pozvan modalPopup koji uzima jedan parametar. U gornjim komentarima koristio sam sintaksu sličnu phpDocumentoru gdje se svakom retku prethodi a @ nakon čega slijedi odabrana tipka. To ni na koji način neće utjecati na vaš kod, tako da možete pisati @opis umjesto @desc bez ikakvih promjena.

Ovi mali ključevi se zapravo nazivaju oznake komentara koje su u velikoj mjeri dokumentirane na web-mjestu. Slobodno izmislite svoje i upotrijebite ih kako želite tijekom koda. Smatram da pomažu da sve to teče Na prvi pogled mogu provjeriti važne informacije. Također biste trebali primijetiti da sam koristio / * * / format komentiranja bloka. Ovo će zadržati sve mnogo čistije nego dodavanje dvostruke kose crte počevši od svakog retka.

Komentari grupe / klase

Osim komentiranja funkcija i petlji, blok područja se ne koriste tako često. Gdje stvarno trebaš jaku blokirati komentare nalaze se na vrhu vaših pozadinskih dokumenata ili knjižničnih datoteka. Lako je ispisati čitavu dokumentaciju za svaku datoteku na vašoj web-lokaciji - tu praksu možemo vidjeti u mnogim CMS-ovima, kao što je WordPress.

Na samom gornjem dijelu vaše stranice trebaju biti komentari koji se odnose na samu datoteku. Na taj način možete brzo provjerite gdje uređujete kada radite na više stranica u isto vrijeme. Osim toga, možete koristiti ovo područje kao bazu podataka za najvažnije funkcije koje su vam potrebne izvan razreda.

/ ** * @desc ova klasa će sadržavati funkcije za korisničku interakciju * ​​primjeri uključuju user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / apstraktna klasa myWebClass  

Možete vidjeti da sam koristio samo malu klasu uzorka za lažne myWebClass kodirati. Dodao sam neke meta informacije s mojim imenom i adresom e-pošte za kontakt. Kada programeri pišu otvoreni izvorni kod, to je općenito dobra praksa kako bi vas drugi mogli kontaktirati radi podrške. To je također solidan način rada u većim razvojnim timovima.

Oznaka @potreban nisam nešto što sam vidio drugdje. U nekoliko svojih projekata pratio sam format, samo na stranicama na kojima sam prilagodio mnogo metoda. Kad god uključite stranice u datoteku, one moraju doći prije nego što ispišete bilo koji kôd. Dakle, dodavanje tih detalja u glavni blok komentara blokova je dobar način zapamtite koje su datoteke potrebne.

Komentiranje prednjeg koda

Sada kada smo obradili 3 važna predložka komentara, pogledajmo još nekoliko primjera. Postoje mnogi programeri koji su se prebacili iz statičkog HTML-a u jQuery i CSS kod. HTML komentari nisu toliko svrsishodni u usporedbi s programskim aplikacijama, ali kada pišete stilske biblioteke i skripte stranica, stvari se s vremenom mogu postati neuredne.

JavaScript slijedi tradicionalniju metodu komentiranja sličnu Java, PHP i C / C++. CSS koristi samo komentare stila bloka označene crtom i zvjezdicom. Imajte na umu da će komentari biti otvoreno prikazani vašim posjetiteljima, budući da ni CSS ni JS nisu raščlanjeni na strani poslužitelja, ali bilo koja od ovih metoda izvrsno funkcionira za ostavljanje informativnih slaganja u vašem kodu za povratak.

Konkretno razbijanje CSS datoteka može biti posao. Svi smo upoznati s ostavljanjem inline komentara koji objašnjava popravak za Internet Explorer ili Safari. Ali vjerujem da se CSS komentiranje može koristiti na razini jQuery i PHP ih koristiti. Prepustite se stvaranju grupa stilova prije nego što se dotaknete nekih detaljnih savjeta za komentiranje koda.

CSS stil grupe

Za one koji su dizajnirali CSS već godinama, to je gotovo druga priroda. Polako pamtite sva svojstva, sintaksu i izgradite vlastiti sustav za stilske listove. Kroz svoj rad stvorio sam ono što zovem grupiranje upariti slične CSS blokove u jedno područje.

Kada se vraćate na uređivanje CSS-a lako mogu pronaći ono što mi treba u nekoliko sekundi. Način na koji odabirete stilove u potpunosti ovisi o vama, a to je ljepota ovog sustava. Imam nekoliko unaprijed postavljenih standarda koje sam naveo u nastavku:

• @resets - uklanjanje margina zadanog preglednika, obnavljanje, fontovi, boje itd.
• @fonts - paragrafi, zaglavlja, blockquotes, veze, kod
• @ navigacija - glavna jezgra navigacija veze web stranice
• @layout - omot, spremnik, bočne trake
• @header & @footer - one mogu varirati ovisno o vašem dizajnu. Mogući stilovi uključuju veze i neuređene popise, stupce podnožja, naslove, pod-navigacije

Kada grupirate stilske listove, pronašao sam sustav označavanja može puno pomoći. Međutim, za razliku od PHP-a ili JavaScripta, koristim jednu @skupina oznaka koju slijedi kategorija ili ključne riječi. U nastavku sam naveo dva primjera kako biste mogli osjetiti što mislim.

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

/ ** @ podnožje grupe, mali fontovi, stupci, vanjski linkovi ** / 

Alternativno možete dodati malo više detalja u svaki blok komentara. Odlučio sam ostanite jednostavni i jednostavni tako da se stilski listovi lako prelaze. Komentiranje je sve o dokumentaciji, tako dugo dok razumijete da je dobro ići!

4 Savjeti za bolje oblikovanje komentara

Prvu polovicu ovog članka potrošili smo na različite formate za komentiranje koda. Razgovarajmo sada o nekim općim savjetima kako bi vaš kod bio čist, organiziran i lako razumljiv.

1. Čuvajte sve čitljivo

Ponekad kao programeri to zaboravljamo pišemo komentare za čitanje. Svi programski jezici koje razumijemo izgrađeni su za strojeve, tako da može biti zamorno pretvoriti u običan pisani tekst. Važno je napomenuti da nismo ovdje da napišemo istraživački rad na razini fakulteta, ali samo napuštam savjete!

funkcija getTheMail () // kod ovdje će izgraditi e-mail / * run code ako naš prilagođeni sendMyMail () poziv funkcije vraća true naći sendMyMail () u /libs/mailer.class.php ćemo provjeriti da li korisnik popunjava sva polja i poruka je poslana! * / if (sendMyMail ()) return true; // zadrži istinu i prikazuje uspjeh na zaslonu

Čak i samo nekoliko riječi Bolje išta nego ništa. Kada se budete vraćali na uređivanje i rad na projektima u budućnosti, to je često iznenađujuće koliko ćete zaboraviti. Budući da ne gledate iste varijable i nazive funkcija svaki dan, obično polako zaboravljate većinu koda. Tako možete nikada ne ostavljajte previše komentara! Ali možete ostaviti previše loših komentara.

Kao opće pravilo, potrebno je malo vremena za pauzu i razmišljanje prije pisanja. Zapitaj se što je najviše zbunjujuće u programu i kako to najbolje objasniti “lutka” Jezik? Također razmotrite zašto pišete kôd točno onako kako jeste.

Neke od najzanimljivijih grešaka pojavljuju se kada zaboravite svrhu prilagođenih (ili trećih strana) funkcija. Ostavite trag komentara koji vodi do nekoliko drugih datoteka ako će vam to olakšati pamćenje funkcionalnosti.

2. Ublažiti neki prostor!

Ne mogu dovoljno naglasiti koliko je važno bijeli prostor Može biti. Ovo ide dvostruko istinito za PHP i Ruby programere koji rade na velikim web-lokacijama sa stotinama datoteka. Vi ćete gledati u ovaj kod cijeli dan! Ne bi li bilo sjajno kad biste mogli proletjeti do važnih područja?

$ dir1 = "/ home /"; // postavi glavni home direktorij $ myCurrentDir = getCurDirr (); // postavljanje trenutnog korisničkog direktorija $ userVar = $ get_username (); // korisničko ime trenutnog korisnika

U gornjem primjeru primijetit ćete dodatni padding koji sam postavio između komentara i koda na svakom retku. Kao što ste pomicanje kroz datoteke, ovaj stil komentiranja će jasno se ističu. To čini pronalaženje pogrešaka i ispravljanje koda stotinama puta lakše kada su promjenjivi blokovi tako čist.

Možete izvršiti sličan zadatak na kodu unutar funkcije gdje ste zbunjeni o tome kako radi, ali ova metoda bi na kraju zakrčila vaš kod s ugrađenim komentarima, a to je upravo suprotno od urednog! Preporučujem u ovom scenariju dodajući veliki komentar blok-linije oko područja logike.

$ (document) .ready (function () $ ('. sub'). hide (); // sakrij pod-navigaciju na pageload / ** provjeri postoji li događaj klikanja na sidru unutar .itm div spriječi zadanu vezu akcija tako da se stranica ne mijenja na pristup klik roditelja element .itm nakon čega slijedi sljedeći .sub popis za prebacivanje otvaranja / zatvaranja ** / $ ('. itm a'). live ('klik', funkcija (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('brzo');););

Ovo je mali dio jQuery koda koji cilja pod-izbornik klizna navigacija. Prvi komentar je inline objasniti zašto smo skrivaju sve .pod klase. Iznad upravljača događaja događaja uživo koristio sam blok komentar i uvučena sva pisma do iste točke. To čini stvari ljepšim, a ne pokusnim - osobito za druge koji čitaju vaše komentare.

3. Komentirajte dok kodirate

Uz pravilan razmak ovo može biti jedan od najboljih navika da se u. Nitko se ne želi vratiti na svoj program nakon što radi i dokumentira svaki komad. Većina nas čak ne želi ići natrag i dokumentirati zbunjujuća područja! Zaista je potrebno puno posla.

Ali ako možete pisati komentare dok kodirate sve će još biti svježe u vašem umu. Obično će se programeri zaglaviti u problemu i pretražiti web za najlakše rješenje. Kada pogodite Eureka trenutak i riješite takav problem, obično postoji trenutak jasnoće u kojem razumijete svoje prethodne pogreške. Ovo će biti najbolje vrijeme ostaviti otvorene i iskrene komentare o svom kodu.

Osim toga, ovo će vam omogućiti da se naviknete na komentiranje svih vaših datoteka. Količina vremena potrebna za povratak i otkrivanje kako nešto radi je mnogo veća nakon što ste već izgradili funkciju. I vaše buduće ja i vaši suigrači će vam zahvaliti što ste unaprijed ostavili komentare.

4. Suočavanje s greškama u buggyu

Ne možemo svi satima sjediti ispred računala pišući kod. Pretpostavljam da možemo pokušati, ali u nekom trenutku moramo spavati! Vjerojatno ćete morati razdvojiti svoj kôd za taj dan, a neke će se značajke još uvijek pokvariti. U ovom scenariju je presudno da vi ostavite duge, detaljne komentare o tome gdje ste ostavili stvari.

Čak i nakon svježeg sna možete biti iznenađeni koliko je teško vratiti se u zamah kodiranja. Na primjer, ako gradite stranicu za prijenos slika i morate je ostaviti nedovršenom, vi trebali komentirati gdje ste u procesu ste stali. Jesu li slike učitane i pohranjene u privremenu memoriju? Ili možda čak nisu ni prepoznate u obrascu za prijenos, ili možda nisu ispravno prikazane na stranici nakon učitavanja.

Komentiranje pogrešaka važno je iz dva glavna razloga. Prvo možete s lakoćom pokupite gdje ste stali i pokušajte ponovno svježe da biste riješili problem (a). I drugo, možete razlikovati verziju produkcije vaše web-lokacije i testiranje. Zapamtite da se na te komentare treba koristiti objasnite zašto radite nešto, nije točno ono što radi.

Zaključak

Razvoj web-aplikacija i softvera je ispunjavajuća praksa, iako teška. Ako ste jedan od rijetkih programera koji uistinu razumije softver za izgradnju, važno je da sazrijete pomoću vještina kodiranja. Ostavljanje opisnih komentara samo je dobra praksa na duge staze, i vjerojatno nećete požaliti!

Ako imate prijedloge za jasnije komentiranje koda, obavijestite nas u području za raspravu u nastavku!