Cod sursă Comentariu sfaturi de styling și cele mai bune practici

Dezvoltatorii care au petrecut orice timp pe proiecte mari înțeleg importanța comentariilor codului. Când construiți multe funcții în aceeași aplicație, lucrurile tind să se complică. Există atât de multe biți de date, inclusiv funcții, referințe variabile, valori returnate, parametri ... cum vă așteptați să țineți pasul?

Ar trebui să nu fie o surpriză faptul că comentarea codului dvs. este esențială, atât în ​​proiecte solo, cât și în echipe. Dar mulți dezvoltatori nu știu cum să procedeze în acest proces. Mi-am prezentat unele dintre trucurile mele personale creând comentariile codificate, bine formatate. Standardele și template-urile de comentarii vor varia între dezvoltatori - dar, în cele din urmă, ar trebui să vă străduiți curate și ușor de citit pentru a explica în continuare zonele confuze în codul dvs..

Ar trebui să discutăm unele dintre diferențele de formatare a comentariilor. Acest lucru vă va oferi o idee mai bună despre cât de detaliată puteți deveni cu codul proiectului. Ulterior, vă voi oferi câteva sfaturi și exemple specifice pe care le puteți începe imediat!

Stiluri de comentariu: o prezentare generală

Trebuie remarcat faptul că aceste idei prezentate sunt simple instrucțiuni spre comentarii mai curate. Limbile individuale de programare nu prevăd instrucțiuni sau specificații pentru configurarea documentației.

Acestea fiind spuse, dezvoltatorii de zile moderne au grupat împreună pentru a-și forma propriul sistem de comentare a codului. Voi oferi cateva stiluri mainstream si voi trece in detaliu scopul lor.

Inline Commenting

Practic, fiecare limbaj de programare oferă comentarii inline. Acestea se limitează la conținutul cu o singură linie și comentează numai textul după un anumit punct. Deci, de exemplu, în C / C ++ începeți un comentariu in linie astfel:

// începe lista variabilelor var myvar = 1; ... 

Acest lucru este perfect pentru a intra în cod în câteva secunde explică funcționalitatea confuză. Dacă lucrați cu numeroși parametri sau apeluri de funcții, puteți localiza o serie de comentarii inline în apropiere. Dar cea mai benefică utilizare este a explicație simplă pentru funcționalități mici.

dacă (callAjax ($ params)) // executați cu succes callAjax cu parametrii de utilizator ... code

Observați mai sus că codul va trebui să fie pe o linie nouă după brațul de deschidere. În caz contrar, totul va fi prins pe aceeași linie de comentarii! Evitați plecarea peste bord deoarece în general nu este nevoie să vedeți comentarii de o singură linie în întregime în josul paginii dvs., dar în special pentru joncțiunile confuzive din codul dvs., acestea sunt mult mai ușor de scăzut în ultimul minut.

Blocuri descriptive

Când trebuie să includeți o explicație largă, în general, o singură linie nu va face truc. Există șabloane de comentarii preformate utilizate în fiecare zonă de programare. Blocuri descriptive sunt cele mai vizibile în jurul funcțiilor și fișierelor de bibliotecă. Ori de câte ori configurați o funcție nouă, este o practică bună adăugați un bloc descriptiv deasupra declarației.

/ ** * @desc deschide o fereastră modală pentru a afișa un mesaj * @param string $ msg - mesajul care va fi afișat * @return bool - succes sau eșec * / funcție modalPopup ($ msg) ... 

Mai sus este un exemplu simplu de comentariu funcțional descriptiv. Am scris o funcție probabil în JavaScript numit modalPopup care ia un singur parametru. În comentariile de mai sus am folosit o sintaxă similară cu phpDocumentor unde fiecare linie este precedată de o @ simbol urmat de o cheie selectată. Acestea nu vă vor afecta în vreun fel codul, astfel încât să puteți scrie @Descriere in loc de @desc fără nici o schimbare.

Aceste chei mici sunt numite de fapt tag-uri de comentariu care sunt documentate foarte mult pe site. Simțiți-vă liber să vă creați propriile dvs. și să le folosiți după cum doriți în întregul cod. Mi se pare că ajută la păstrarea tot ceea ce curge Pot să văd informații importante dintr-o privire. Ar trebui să observați, de asemenea, că am folosit / * * / în formă de bloc de comentarii. Acest lucru va păstra totul mult mai curat decât adăugând o lovitură dublă începând de la fiecare linie.

Comentariile de grup / clasă

Pe lângă comentarea funcțiilor și a buclelor, zonele de bloc nu sunt utilizate la fel de frecvent. Unde ai nevoie cu adevărat puternică blocați comentariile sunt în fruntea documentelor de backend sau a fișierelor de bibliotecă. Este ușor să faceți totul și să scrieți documentația solidă pentru fiecare fișier de pe site-ul dvs. - putem vedea această practică în multe CMS cum ar fi WordPress.

Zona de sus a paginii dvs. ar trebui să conțină comentarii cu privire la fișierul în sine. În acest fel poți verificați rapid unde editați când lucrați în mai multe pagini în același timp. În plus, puteți utiliza această zonă ca o bază de date pentru cele mai importante funcții de care aveți nevoie din clasă.

/ ** * @desc această clasă va deține funcții pentru interacțiunea cu utilizatorul * exemplele includ user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / clasa abstractă myWebClass  

Puteți vedea că am folosit doar o mică probă pentru fals myWebClass cod. Am adăugat câteva informații despre meta cu numele meu și adresa de e-mail pentru contact. Când dezvoltatorii scriu cod sursă deschisă, aceasta este, în general, o practică bună, astfel încât alții să vă poată contacta pentru asistență. Aceasta este, de asemenea, o metodă solidă atunci când lucrează în echipe de dezvoltare mai mari.

Eticheta @necesar nu este ceva ce am văzut folosit în altă parte. Am ținut pasul cu formatul în câteva dintre proiectele mele, numai pe paginile în care am personalizat o mulțime de metode. Ori de câte ori includeți pagini într-un fișier, acestea trebuie să vină înainte să scoateți orice cod. Așadar, adăugarea acestor detalii în blocul principal de comentarii este o modalitate bună amintiți ce fișiere sunt necesare.

Front-end Codul Comentariu

Acum că am acoperit 3 șabloane de comentarii importante, să aruncăm o privire la câteva exemple. Există mulți dezvoltatori frontend care s-au mutat de la static HTML în jQuery și cod CSS. Comentariile HTML nu sunt la fel de intenționate în comparație cu aplicațiile de programare, dar atunci când scrieți biblioteci de stil și scripturi de pagină, lucrurile pot deveni dezordonate în timp.

JavaScript urmărește o metodă tradițională de comentare similară cu Java, PHP și C / C++. CSS folosește doar comentariile în stil bloc, delimitate de un slash și asterisc. Trebuie să vă amintiți că comentariile vor fi afișate în mod deschis vizitatorilor dvs., deoarece nici CSS, nici JS nu sunt analizate pe server, dar oricare dintre aceste metode funcționează excelent pentru a lăsa tid-uri informative în codul dvs. pentru a vă întoarce.

Ștergerea în mod specific a fișierelor CSS poate fi o corvoadă. Suntem cu toții familiarizați cu lăsarea unui comentariu inline pentru a explica o soluție fixă ​​pentru Internet Explorer sau Safari. Dar cred că comentarea CSS poate fi folosită la nivelul jQuery și PHP. Hai să ne îndrăgim să creăm grupuri de stil înainte de a atinge câteva sfaturi detaliate pentru comentarea codului.

CSS Style Groups

Pentru cei care au proiectat CSS de ani de zile aproape că vine ca a doua natură. Veți memoriza lent toate proprietățile, sintaxa și construiți propriul sistem pentru foile de stil. Prin munca mea am creat ceea ce eu numesc grupare pentru a asocia blocuri CSS similare într-o singură zonă.

Când mă întorc pentru a edita CSS pot găsi cu ușurință ceea ce am nevoie în câteva secunde. Modul în care alegeți să modelați stiluri de grup este în întregime de dvs. și asta este frumusețea acestui sistem. Am câteva standarde prestabilite pe care le-am subliniat mai jos:

• @resetsets - luarea marginilor implicite ale browserului, a padding-ului, a fonturilor, a culorilor etc..
• @fonts - paragrafe, titluri, blockquotes, link-uri, cod
• @navigation - principalele linkuri de navigare pentru site-ul principal
• @layout - ambalaj, container, bare laterale
• @header & @footer - acestea pot varia în funcție de design. Posibilele stiluri includ linkuri și liste neordonate, coloane din subsol, titluri, sub-navă

Când grupați foile de stil am găsit sistem de etichetare poate ajuta foarte mult. Cu toate acestea, spre deosebire de PHP sau JavaScript, folosesc un singur @grup etichetă urmată de o categorie sau cuvinte cheie. Am inclus 2 exemple de mai jos, astfel încât să puteți simți ce vreau să spun.

/ ** @group footer * / #footer stiluri ...

/ ** @group footer, fonturi mici, coloane, link-uri externe ** / 

Alternativ, puteți adăuga un pic de detaliu în fiecare bloc de comentarii. Eu aleg păstrați lucrurile simple și simple astfel încât foile de stil sunt ușor de înțeles. Comentariile se referă doar la documentație, atâta timp cât înțelegeți scrisul pe care trebuie să-l faceți!

4 sfaturi pentru a îmbunătăți stilul de comentarii

Am petrecut prima jumatate a acestui articol uitandu-se la diferitele formate pentru comentarea codului. Să discutăm acum unele sfaturi generale pentru a vă păstra codul curat, organizat și ușor de înțeles.

1. Păstrați totul ușor de citit

Uneori, în calitate de dezvoltatori, uităm asta scriem comentarii pentru ca oamenii să citească. Toate limbile de programare pe care le înțelegem sunt construite pentru mașini, astfel încât poate fi dificil să se transforme în text scris simplu. Este important să rețineți că nu suntem aici pentru a scrie o lucrare de cercetare la nivel de colegiu, dar lăsând sfaturi!

funcția getTheMail () // codul aici va construi codul de e-mail / * dacă comanda vocală personalizată sendMyMail () returnează true findMyMail () în /libs/mailer.class.php verificăm dacă utilizatorul completează toate câmpurile și mesajul este trimis! * / if (sendMyMail ()) return true; // păstrați adevărat și afișați succesul pe ecran

Chiar și câteva cuvinte sunt mai bine decat nimic. Când vă întoarceți să editați și să lucrați pe proiecte în viitor, este de multe ori surprinzător cât de mult veți uita. Deoarece nu vă uitați la aceleași nume de variabile și funcții în fiecare zi, aveți tendința de a uita lent majoritatea codului. Astfel puteți nu lăsați prea multe comentarii! Dar puteți lăsa prea multe comentarii proaste.

Ca regulă generală, ia ceva timp pentru a întrerupe și a reflecta înainte de a scrie. Intreaba-te pe tine insuti ceea ce este cel mai confuz cu privire la program și cum poți să-i explici cel mai bine “fictiv” limba? De asemenea, ia în considerare de ce scrieți codul exact așa cum vă aflați.

Unele dintre cele mai confuze erori apar atunci când uitați scopul funcțiilor construite (sau terțe părți) personalizate. Lăsați o pistă de comentarii care să conducă la câteva alte fișiere dacă acest lucru vă va ajuta să vă amintiți mai ușor funcționalitatea.

2. Reduceți spațiul!

Nu pot să subliniez cât de importantă este spatiu alb poate fi. Asta merge dublu adevărat pentru dezvoltatorii PHP și Ruby care lucrează pe site-uri masive cu sute de fișiere. Veți observa acest cod toată ziua! Nu ar fi minunat dacă ați putea să ajungeți în zonele importante?

$ dir1 = "/ home /"; // setați principalul director de domiciliu $ myCurrentDir = getCurDirr (); // setați directorul curent al utilizatorului $ userVar = $ get_username (); // nume de utilizator actual al utilizatorului

În exemplul de mai sus, veți observa o umplutură suplimentară pe care am plasat-o între comentarii și cod pe fiecare rând. Pe măsură ce defilați prin fișiere, acest stil de comentare va fi ieșiți clar. Aceasta face ca găsirea de erori și corectarea codului dvs. de sute de ori mai ușoară când blocurile variabile sunt așa curat.

Ați putea efectua o activitate similară pe codul din interiorul unei funcții în care sunteți confuz în legătură cu modul în care funcționează, dar această metodă vă va dezamăgi în cele din urmă codul cu comentarii inline și acesta este exact opusul ordinii! Vă recomandăm în acest scenariu adăugând un comentariu mare despre linia de bloc în jurul zonei logice.

$ hide (); // ascunde sub-navigarea pe pageload / ** verifica pentru un eveniment clic pe o ancora în interiorul .itm div împiedica link-ul implicit acțiune astfel încât pagina nu se schimbă la accesul la clic, elementul părinte al .itm urmat de următoarea listă .sub pentru a comuta deschide / închide ** / $ ('. itm a') live ('clic', funcția ) e.preventDefault (); $ (acest) .parent () următorul ('.sub)' slideToggle ('rapid');););

Acesta este un mic fragment de cod jQuery care vizează o navigație de navigare sub-meniu. Primul comentariu este inline pentru a explica de ce ascundem toate .Sub clase. Deasupra handlerului evenimentului cu clicuri live am folosit un comentariu bloc și cu totul scris în același punct. Acest lucru face ca lucrurile mai frumoase, mai degrabă decât rularea paragrafelor - în special pentru alții care vă citesc comentariile.

3. Observați în timp ce codificați

Împreună cu distanțele adecvate aceasta poate fi una dintre cele mai bune obiceiuri de a intra în. Nimeni nu vrea să se întoarcă peste programul lor după ce lucrează și documentează fiecare piesă. Cei mai mulți dintre noi nu doresc să se întoarcă și să documenteze zonele confuze! Este într-adevăr nevoie de multă muncă.

Dar dacă puteți scrie comentariile în timp ce codificați totul va fi în continuare proaspăt în mintea ta. De obicei, dezvoltatorii se vor lipi de o problemă și vor curăța web pentru cea mai ușoară soluție. Când atingi momentul Eureka și rezolvi o astfel de problemă, există, în general, un moment clar în care înțelegi erorile tale anterioare. Aceasta ar fi cel mai bun timp să lăsați comentarii deschise și oneste despre codul dvs..

În plus, acest lucru vă va oferi o practică de a vă obișnui să comentați toate fișierele. Timpul necesar pentru a vă întoarce și a afla cum funcționează ceva este mult mai mare după ce ați construit deja funcția. Atât viitorul dvs. cât și coechipierii dvs. vă vor mulțumi pentru că ați lăsat comentarii înainte.

4. Confruntarea cu erorile bug-urilor

Nu putem toți să stăm în fața calculatorului timp de ore de scriere a codului. Presupun că putem încerca, dar la un moment dat trebuie să dormim! Probabil că va trebui să dezactivați codurile pentru ziua respectivă, cu unele caracteristici încă rupte. În acest scenariu este esențial să vă lăsați comentarii lungi și detaliate despre locul unde ați lăsat lucrurile departe.

Chiar și după o noapte de somn proaspăt s-ar putea să fiți surprins de cât de dificil poate fi să vă întoarceți în leagăn de codificare. De exemplu, dacă construiți o pagină de încărcare a imaginii și trebuie să o lăsați neterminată, tu ar trebui să comenteze despre locul în care ați rămas. Sunt încărcate și stocate imagini în memorie temporară? Sau poate că nici măcar nu sunt recunoscute în formularul de încărcare sau poate că nu sunt afișate corect pe pagină după încărcare.

Erorile de comentare sunt importante din două motive principale. Mai întâi poți luați cu ușurință locul în care ați rămas și încercați din nou proaspăt la minte pentru a remedia problema (problemele). Și în al doilea rând poți diferențiați între versiunea de producție live a site-ului dvs. web și terenurile de testare. Amintiți-vă că ar trebui folosite comentariile explicați de ce faceți ceva, nu exact ceea ce face.

Concluzie

Dezvoltarea aplicațiilor web și a software-ului este o practică satisfăcătoare, deși dificilă. Dacă sunteți unul dintre puținii dezvoltatori care înțeleg cu adevărat software-ul de construcție, atunci este important să vă maturizați cu abilitățile de codare. Lăsarea de comentarii descriptive este doar o bună practică pe termen lung, și probabil că nu veți regreta niciodată!

Dacă aveți sugestii pentru comentarea mai clară a codului, informați-ne în zona de discuții de mai jos!