Share
Când vine vorba de scrierea de cod, indiferent de limbajul sau platforma utilizată, dezvoltatorii tind să fie împărțiți pe cât de mult sau cât de puțin ar trebui să comentăm codul nostru.
Pe de o parte, există unii care cred că acest cod ar trebui să se auto-documenteze. Adică ar trebui să fie scris suficient de clar astfel încât să nu aibă nevoie de comentarii.
Pe de altă parte, unii cred asta Tot ar trebui să fie comentate. Adică, ar trebui să existe comentarii pentru fiecare clasă, fiecare funcție, fiecare bloc și fiecare linie.
Apoi, desigur, sunt cei care cad în mijloc. De fapt, unii dezvoltatori comentează doar zone din codul lor care ar putea fi confuz, mai degrabă decât alegerea abordării "totul sau nimic" subliniată mai sus.
Când vine vorba de a scrie cod pentru WordPress, avem WordPress Coding Standards pentru a oferi un standard prin care ar trebui să ne scriem codul nostru; cu toate acestea, nu oferă un caz puternic pentru sau împotriva comentariilor codului.
În această serie de articole, voi oferi un caz pentru codul de comentarii. În mod specific, am de gând să acopere de ce contează, o recomandare pentru a face acest lucru în contextul fișierelor standard WordPress necesare (pentru ambele teme și pluginuri) și cum să faceți acest lucru pentru fișierele HTML, foile de stil și JavaScript fișiere.
Înainte de a privi diversele părți care alcătuiesc un proiect WordPress, cred că este important să discutăm de ce contează comentariile de la cod. Sigur, majoritatea dintre noi știu că este de a oferi o scurtă explicație cu privire la ceea ce se întâmplă cu codul, dar implicațiile sunt mai mari decât.
În ciuda faptului că avem standarde prin care noi ar trebui să scrieți codul bazat pe WordPress, unii dezvoltatori îi tratează ca "recomandări", să nu mai vorbim de cei care nici măcar nu sunt conștienți de ele. Indiferent de cât de bine (sau cât de rău) vă scrieți codul, este încă cod.
La urma urmei, dacă ar fi ușor de înțeles, nu se va numi cod (și nu am avea nevoie de comentarii).
Nu cred că ar trebui să scriem comentarii de cod numai cu alții în minte. Cred că ar trebui să le scriem pentru noi înșine, la fel de mult. Când revizuiți codul pentru prima dată după ce a trecut o perioadă semnificativă de timp, este foarte probabil că ați devenit un programator mai bun, ați luat câteva tehnici noi și / sau ați trecut mai departe de modul în care ați scris codul. Astfel, poate fi dificil să discernem ceea ce încercați să faceți.
Și dacă este dificil pentru autorul codului să urmeze, ce speranță există pentru alți dezvoltatori care contribuie, extind sau îmbunătățesc codul?
În cele din urmă, comentariile trebuie să fie scrise atât pentru noi, cât și pentru cei care pot interacționa cu codul nostru. Acestea ar trebui să fie clare, concise și ar trebui să furnizeze orice informație necesară pe care un dezvoltator ar trebui să o cunoască pentru a putea lucra cu respectiva secțiune de cod. Aceasta include orice informație care face referire la cod în alte (de la server sau de la client).
Cu asta am spus că aș dori să acorde câteva motive și strategii pentru a comenta toate fișierele care au loc în crearea unei teme WordPress, a unui plugin sau a unei aplicații.
În funcție de proiect, fișierele pe care trebuie să le includeți sunt diferite. În sensul prezentului articol, presupun că includeți fișiere PHP, fișiere HTML, fișiere de stil și fișiere JavaScript, pentru a vă asigura că toate bazele sunt acoperite. În acest articol, vom discuta limbajul de pe server - adică PHP - iar în următorul articol vom examina limbile de la client.
Când vine vorba de comentarea fișierelor noastre PHP, există mai multe cerințe pe care trebuie să le urmăm:
În afară de aceasta, există într-adevăr foarte puțin comentări necesare, deci există evident loc de îmbunătățire.
Când vine vorba de comentarea codului în PHP, există de fapt un mod sugerat de a face acest lucru - PHPDoc. Similar cu standardele de codare WordPress, PHPDoc este un standard pentru comentarea (sau documentarea) codului PHP. Acesta oferă o serie de convenții care sunt toate aplicabile WordPress, dar un subset despre care văd folosit în mod regulat.
WordPress acceptă două tipuri de fișiere șablon:
Când vine vorba de documentarea fișierelor șablon - indiferent de tipul de șablon - întotdeauna încerc să furnizez informații de antet care definesc numele fișierului, scopul fișierului, pachetul - sau tema sau plugin - din care face parte, și cât timp a existat în proiect.
De exemplu:
/ ** * Nume șablon: Proiecte recomandate * * Șablonul folosit pentru zona "Proiecte speciale" din pagina de pornire. Faceți clic pe tipul de postare "Proiecte recomandate" și trageți cele mai recente trei intrări. * * @Package Tema de proiect * @ începând cu 1.0 * /
După cum puteți vedea, am oferit cerințele Nume șablon pentru dosar, dar am oferit și o scurtă descriere a ceea ce se întâmplă în dosar. Am folosit de asemenea @pachet și @de cand directive pentru a ajuta la clarificarea mai multor aspecte.
@pachet directiva, cel puțin în contextul WordPress, reprezintă numele temei sau pluginului din care face parte acest fișier.
@de cand Directiva reprezintă cât timp a existat șablonul în proiect. În cazul de mai sus, este evident că a fost în proiect de la lansarea sa inițială, dar nu este deloc neobișnuit să adăugați fișiere ca o temă sau ca plugin-ul se maturizează, rezultând astfel un alt număr de versiune care apare ca această valoare.
Datorită naturii fișierelor de șablon de bază, cum ar fi indexul, șabloanele unice, paginile, arhivele și așa mai departe, nu este nevoie să definiți o "Nume șablon,"dar descrierea, pachetul și din moment ce directivele sunt încă relevante.
Funcțiile de documentare sunt foarte asemănătoare cu șabloanele de documentare. Deși nu necesită o etichetă specifică - cum ar fi "Nume șablon"- ar trebui să includă în continuare o descriere a scopului funcției și a funcției @de cand directivă.
Există, de asemenea, două directive suplimentare, o funcție care poate include opțional:
Accentsconagua
@param care descrie tipul și descrierea unui parametru pe care funcția îl acceptă@întoarcere care descrie tipul și descrierea a ceea ce revine funcțiaDesigur, funcțiile nu acceptă întotdeauna parametrii și funcțiile nu întorc întotdeauna valori, motiv pentru care aceste două directive sunt opționale.
Presupunând că aveți o funcție care să susțină ambele directive de mai sus, trebuie să așteptați ca documentația să apară:
/ ** * Introduce programatic o pagină în baza de date. * * @param $ title Titlul paginii. Varianta cu litere mici funcționează, de asemenea, ca pagina de slug. * @param $ template_name Numele fișierului șablon situat în directorul "șabloane". * @return ID-ul paginii care a fost creată * @ începând cu 1.0 * /
Pentru mai multe informații despre fiecare dintre aceste directive, puteți consulta etichetele PHPDoc; cu toate acestea, puteți vedea cât de util poate fi acest lucru pentru a lucra pe o temă sau un plugin - este nevoie de o mulțime de durere din a fi nevoit să discerne ceea ce dvs. sau un alt dezvoltator ați încerca să realizați cu o anumită funcție.
Deși există câteva recomandări sau standarde reale pentru documentarea blocurilor de cod, cred că este utilă mai ales atunci când vine vorba de bucle sau condiționări mai complicate.
Toate acestea pot fi demonstrate în exemplul următor: Să presupunem că trebuie să setăm o interogare particularizată pentru a rula prin meta date post și apoi să o ștergem dacă se găsește o anumită cheie și / sau o valoare. Aceasta ar necesita următorii pași:
Acest exemplu va document atât linii unice, cât și condiționate. Mai întâi, să aruncăm o privire la codul sursă și apoi vom examina ce face imediat după aceasta:
// Argumentele de instalare pentru a prelua toate postările publicate $ argumente = array ('post_type' => 'post', 'post_status' => 'publicați','posturi '=> -1); // Instanțiați interogarea $ posts_query = noi WP_Query ($ arguments); // Dacă se găsesc postări, le rupeți dacă ($ posts_query-> have_posts ()) while ($ posts_query-> have_posts ()) $ posts_query-> the_post (); / * * Pentru fiecare piesă de meta care se găsește, stocați-i valorile în * meta_key și $ meta_value pentru ca noi să le verificăm. * / foreach (get_post_meta (get_the_ID ()) ca $ meta_key => $ meta_value) / * * Pot exista mai multe chei meta (cum ar fi tweet_url_0, tweet_url_1) * asa ca trebuie sa verificam daca se gaseste tweet_url în * meta_key. * Dacă da, putem să ștergem meta datele postului * / if (false! = Strstr ($ meta_key, 'tweet_url')) delete_post_meta (get_the_ID (), $ meta_key); // end if // end foreach // end while // // end if // Resetați interogarea personalizată astfel încât să nu interfereze cu alte interogări sau Loop wp_reset_postdata (); În mod ideal, comentariile de mai sus trebuie să furnizeze toată documentația și explicația necesară pentru a înțelege ce se întâmplă în cod. Poate că singurul lucru care ar putea fi necesar este înțelegerea strstr funcţie.
Punctul-cheie pe care încerc să-l fac cu codul de mai sus este că, dacă documentăm linii unice, atunci este mai bine să rămânem la convenția unei singure linii - adică // - dar dacă scriem un comentariu care se întinde pe mai multe linii, este întotdeauna mai bine să folosiți comentariul multiline - adică / * * /.
Observați, de asemenea, că nu fiecare linie are pentru a fi comentat. Mai degrabă, blocurile (sau fragmentele) de cod pot fi explicate într-un comentariu pe mai multe linii care documentează ce urmează să se întâmple în următorul cod sursă.
Desigur, acest lucru nu este un mod standard sau un mod preferat de a face lucrurile. Este doar o strategie pe care am văzut-o folosită, pe care o apreciez și pe care o folosesc eu.
Dacă ajungeți în urma convențiilor stabilite în PHPDoc, atunci există un număr de utilitare care pot genera pagini de documentație pentru munca dvs. În mod evident, instrumentul cel mai popular este phpDocumentor.
Pe scurt, phpDocumentor este un utilitar care va trece prin codul dvs. sursă în căutarea corectă a codificării codurilor PHPDoc (în mod special pe clase și funcții) și va genera apoi un set de pagini șablon care captează informațiile din comentariile dvs..
Aceasta face ca documentația orientată spre dezvoltatori pentru transport maritim să fie însoțită de aplicația dvs. un cinch.
În tot acest articol, am abordat 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. Deși Codul WordPress definește un set de comentarii de bază necesare pentru munca noastră și / sau pentru a interfața cu aplicația WordPress, există evident mai multă muncă pe care o putem face pentru a îmbunătăți claritatea codului nostru.
Chestia e că am acoperit doar jumătate din ea. Deci, în următorul articol, vom examina documentarea marcajului, JavaScript și stiluri.
@pachet Directivă@de cand Directivăstrstr