Share
În această serie din două părți, ne uităm la construirea unui caz pentru comentarii de cod. În primul articol, ne-am referit la server, aruncându-ne o privire la PHP. Mai precis, am revizuit convențiile PHPDoc și modul de utilizare a acestora pentru a documenta șabloanele, funcțiile, liniile și blocurile.
În acest articol, vom examina limbajele clientului. Mai precis, vom analiza HTML, CSS și JavaScript.
Deși nu există neapărat utilități de documentare cum ar fi phpDocumentor pentru toate aceste limbi, există încă strategii pe care le putem folosi pentru a ne menține proiectele (sau pentru a ajuta alții să contribuie la proiectele noastre) un pic mai ușor.
Când vine vorba de a lucra cu WordPress, temele și pluginurile vor varia în funcție de tipul de fișiere pe care le includ. Temele vor consta, de regulă, din HTML și CSS și probabil unele din JavaScript, în timp ce pluginurile Mai constă doar din PHP.
În primul articol, ne-am uitat la ceea ce WordPress necesită pentru a înregistra fișierele șablon cu API, precum și ce pluginuri au nevoie. Înainte de a citi mai departe, vă recomand să revizuiți acest articol mai întâi deoarece acoperă informațiile solicitate, în timp ce acest articol se referă doar la recomandarea pentru ceea ce putem face pentru a ne îmbunătăți comentariile.
Majoritatea dezvoltatorilor web sunt conștienți de modul de scriere a comentariilor în contextul HTML. Pur și simplu, este o chestiune de prefixare a codului - fie că este o singură linie sau bloc - cu . Când vine vorba de scrierea marcajului, nu este deloc comun să vezi comentarii dincolo de condiționalități pe care le vei găsi în cap element al documentului.
Există tehnici pe care le putem folosi pentru a face codul nostru mai ușor de întreținut. Acest lucru este util în special atunci când lucrați cu sisteme precum WordPress, deoarece anumite elemente vor fi distribuite în mai multe fișiere.
De exemplu, presupunând că construiți o temă, probabil că vă veți deschide corp element și un element container în header.php șablon și terminând apoi elementele din footer.php șablon.
Acesta este un exemplu simplificat, deoarece este relativ comun, dar principiul rămâne adevărat prin celelalte fișiere.
Cu asta am spus că există o strategie simplă pe care o putem folosi pentru a comenta codul nostru:
Elementele HTML vor fi în general în una din cele patru forme:
Pentru fiecare dintre aceste permutări, respect următoarele convenții:
Mai sus, există un fragment de cod pentru un formular utilizat pentru salvarea opțiunilor în formularul de bază de date WordPress din tabloul de bord. În acest caz, în mod normal, voi lăsa un comentariu la sfârșitul elementului care indică scopul formei sau alt atribut, cum ar fi atributul de acțiune.
Având în vedere această strategie, exemplul de mai sus poate arăta astfel:
Sau:
Convenția pe care o folosesc este să folosesc un backslash - în mod normal HTML - urmat de scopul de a descrie elementul care să-mi spună că termin acest element.
Deși acest lucru nu poate fi deosebit de util cu un singur element izolat, am descoperit că este util cu elemente imbricate, precum și atunci când un element - ca un container - este împărțit între fișiere.
În cazul în care elementul are un ID, folosesc următorul comentariu:
La fel ca mai sus, folosesc un backslash urmat de un "#"care reprezintă un ID în CSS urmat de numele valorii atributului ID. Vreau să știu că termin un element cu ID-ul dat.
Din nou, acest lucru este foarte util când un element există între fișiere, dar este, de asemenea, util atunci când trebuie să faceți o căutare globală în fișiere șablon sau în fișiere CSS.
Atunci când un element include numai o clasă (sau un set de clase), am o strategie similară celei de mai sus - folosesc un backslash, indicatorul CSS pentru o clasă și apoi clasa (sau prima clasă) pe element:
Destul de simplu.
Dar ce se întâmplă când elementul include atât o identitate, cât și o clasă? Din moment ce ID-urile sunt unice și numele de clasă nu sunt, întotdeauna am întotdeauna implicit să folosesc ID-ul elementului la terminarea comentariului:
Are sens, nu? Iar punctul rămâne încă: Acest lucru face mai ușor să știți care element se termină și îl face ușor să îl găsiți în restul fișierelor proiectului.
JavaScript este similar cu PHP, deoarece acceptă caracteristici de ordin superior, cum ar fi funcțiile (și prototipurile dacă scrieți JavaScript de la vanilla). Din acest motiv, este utilă o convenție prin care să ne documentăm funcțiile.
Iată lucrul: WordPress include jQuery în mod implicit, astfel încât este comun pentru majoritatea JavaScript specific WordPress să fie scris folosind o combinație de jQuery bazate pe JavaScript și caracteristici bazate pe vanilla, cum ar fi funcții.
Următoarele strategii s-au dovedit utile în scrierea JavaScript în WordPress:
În primul rând, încerc să denumesc fișierul în funcție de scopul pe care îl servește (cum ar fi navigation.js sau theme.js sau admin.js).
În al doilea rând, voi oferi, de asemenea, o scurtă descriere în partea de sus a fiecărui fișier folosind convențiile PHPDoc pentru descrierea fișierului și cât timp a făcut parte din proiect:
/ ** * admin.options.js * * Gestionează gestionarea evenimentelor pentru mai multe elemente pe pagina opțiunilor tabloului de bord. * * @ de la 1.0 * @ versiunea 3.2 * /
Pentru funcții, urmează o convenție similară ca mai sus, în care voi oferi o scurtă descriere a funcției, descriu ce acceptă și ce se întoarce, precum și cât timp a fost în proiect și versiunea curentă a fișierului:
/ ** * Funcția Helper care este concediată atunci când utilizatorul dă clic pe "Done" sau apasă "Enter" * atunci când lucrează pentru salvarea icoanelor lor sociale. * * @param $ O referință la funcția jQuery * @param evt Evenimentul sursă al acestui handler * @returns Dacă utilizatorul a intrat sau a anulat opțiunea pentru a salva opțiunile. * @ de la 1.0 * @ versiunea 1.2 * /
Acest lucru nu este nimic mai mult decât comentariile standard de cod pe care majoritatea dezvoltatorilor le folosesc adesea. Există variația unei singure linii, variația multiline și scopul pe care îl servesc: adică pur și simplu pentru a descrie ce urmează să se întâmple în codul care urmează comentariului.
Accentsconagua
/ * * Dacă ne uităm la pictograma feedului RSS, dezactivați intrarea * și conectați utilizatorul la opțiunile globale pentru unde să îl setați. * / if ("! == sRssUrl) $ ('# social-icon-url') .val (sRssUrl) .attr (' url ') removeAttr (' dezactivat '); // // end if Există foarte puține lucruri pe care să le adăugăm la acest lucru pe care nu le-am abordat în primul articol, dar am vrut să-l menționez aici pentru revizuire și pentru a fi completat.
Deși nu există un instrument oficial de documentare JavaScript, jsDoc a devenit una dintre cele mai comune utilitare pentru documentarea codului JavaScript.
Comentând fișierele CSS este cu siguranță mult mai ușor decât să lucrezi cu PHP sau cu markup deoarece există într-adevăr doar o singură cale de a scrie stiluri.
Asta înseamnă că definiți stiluri pentru un element care utilizează un ID sau o clasă:
# nr-comentarii font-size: 24px; linia-înălțime: 36px; font-weight: bold; culoare: # 444;
Sau:
.acasă .stic: înainte de display: inline-block; fundal: url transparent (imagini / sticky.png) no-repeat; lățime: 58px; înălțime: 45px; conținut: ""; poziția: absolută; top: 26px; stânga: -9px;
În general vorbind, nu cred că trebuie să comentezi stiluri, dar dacă te afli într-o situație în care convorbirea terminată este în afara ecranului, atunci ar putea fi util să termini stilul cu un comentariu ca acesta:
# nr-comentarii font-size: 24px; linia-înălțime: 36px; font-weight: bold; culoare: # 444; /* #fara comentarii */
Sau:
.acasă .stic: înainte de display: inline-block; fundal: url transparent (imagini / sticky.png) no-repeat; lățime: 58px; înălțime: 45px; conținut: ""; poziția: absolută; top: 26px; stânga: -9px; / *. home: înainte de * /
În acest moment, utilizarea limbilor precum LESS și Sass și preprocesoarele lor devine tot mai populară în dezvoltarea web-ului. Una dintre cele mai comune caracteristici ale acestor două limbi este că acestea suportă reguli imbricate.
În acest caz, cred că există un caz mult mai puternic pentru utilizarea comentariilor. De exemplu:
#header #slideshow # imagine-list style-list: none; plutește la stânga; marja: 0; lățime: 100%; // # # imagine-list // #slideshow // #header
În acest fel, știți ce element închideți indiferent de locul în care elementul începe în IDE.
De-a lungul acestei serii, am subliniat de ce cred că comentariile despre cod ar trebui să fie ceva pe care toți dezvoltatorii ar trebui să îl includă în codul lor. În acest articol, am discutat strategiile mele despre modul în care coment comentariul meu, JavaScript și stilurile mele.
Deși nu spun că drumul meu este numai mod de a scrie comentarii - este doar o modalitate - cred că includerea comentariilor merge mult în a face un proiect mai ușor de întreținut pentru dvs. și colegii dvs. și cred că includerea lor în munca dvs. este ceva pe care fiecare dezvoltator ar trebui să aibă ca scop.
Sperăm că această serie a oferit un caz pentru asta. Indiferent, mi-ar plăcea să vă aud gândurile și sugestiile în comentarii.
