Acasă Adult66 Actualizarea standardelor de codare pentru PHP moderne

Adult66

Actualizarea standardelor de codare pentru PHP moderne

192

Pana in luna mai a anului trecut, contributiile la WordPress Core Core este setul de software necesar pentru a rula WordPress. Echipa de Dezvoltare Core dezvolta WordPress. au fost legate de PHP Limbajul de script web in care WordPress este arhivat in primul rand. WordPress necesita sintaxa PHP 5.6.20 5.2 si majoritatea pluginurilor si temelor lipite de cerinta minima PHP 5.2.

Cu toate acestea, odata cu modificarea la PHP 5.6 ca versiune PHP minima pentru WordPress Core, noile functii PHP au devenit disponibile pentru utilizarea in WP Core si cu perspectiva unei versiuni minime de PHP 7.x in viitorul (aproape), chiar mai mult functiile interesante de limbaj vor deveni curand disponibile pentru utilizare in WordPress Core, pluginuri si teme.

Avand in vedere acest lucru, am dori sa definim standarde de codare pentru o serie de constructii si sa ne propunem sa implementam verificari automate pentru acestea in instrumentele de codare WordPress in viitorul apropiat.

Desi poate fi inca ceva timp pana cand unele dintre aceste caracteristici vor fi de fapt adoptate pentru a fi utilizate in WordPress Core, definirea in avans a standardelor de codare va permite o baza de cod consistenta atunci cand se adopta si va permite pluginuri si teme, care sunt nu este neaparat legat de minimul PHP 5.6, pentru a-si pastra coerenta codului atunci cand incep sa foloseasca deja PHP mai modern.

Ca sa fiu sincer, niciuna dintre aceste propuneri nu este teribil de interesanta, iar unele pot parea ca nu merita mentionate. Cei mai multi urmeaza fie tehnica anterioara in standardele WordPress Core, fie standardele industriei pentru acelasi lucru, dar in spiritul deschiderii, am dori sa verificam asumarea acestora inainte de a le implementa.

Deci, fara alte detalii, urmatoarele standarde de codare sunt propuse pentru implementare in Standardele de codare WordPress 3.0.0:

Reguli pentru constructii PHP moderne

Declaratii ale spatiului de nume

Standarde propuse:

Cuvantul cheie pentru spatiul de nume ar trebui sa fie minuscule.
Ar trebui sa existe exact un spatiu intre cuvantul cheie al spatiului de nume si inceputul numelui spatiului de nume intr-o declaratie a spatiului de nume.
Si pentru a fi mai clar: numele spatiului de nume dintr-o declaratie privind spatiul de nume nu ar trebui sa inceapa cu o retragere principala \. In orice caz, aceasta ar fi o eroare de analiza.
Fiecare „frunza” a unui nume de spatiu de nume ar trebui sa fie in Camel_Caps, adica fiecare cuvant ar trebui sa inceapa cu majuscula si cuvintele ar trebui sa fie separate printr-o subliniere.
Capacele consecutive, ca in cazul acronimelor, vor fi permise. Aceasta este in conformitate cu alte conventii de denumire WP.
Nu trebuie sa existe spatiu alb sau comentarii in partea de nume a declaratiei privind spatiul de nume.
Ar trebui sa existe exact o linie goala inainte de declararea spatiului de nume.
Ar trebui sa existe cel putin o linie goala dupa o declaratie privind spatiul de nume.
Ar trebui sa existe o singura declaratie pentru spatiu de nume.
Acest lucru implica automat ca declaratia de spatiu de nume ar trebui sa se afle in partea de sus a unui fisier, cu doar documentul de blocare a fisierului (phpdoc, xref, docuri inline) si o declaratie de declarare optionala precedenta.
Declaratia de spatiu de nume folosind blocul de breton cret este termenul abstract folosit pentru a descrie unitatile de marcare care, compuse impreuna, formeaza continutul sau aspectul unei pagini web folosind editorul WordPress. Ideea combina concepte despre ceea ce in trecut s-ar fi putut realiza cu coduri scurte, HTML personalizate si descoperirea integrarii intr-o singura API consistenta si experienta utilizatorului. sintaxa nu este permisa.
Declaratiile spatiului de nume fara nume (= spatiu global de nume explicit) nu sunt permise.

Problema WPCS deschisa conexa: https://github.com/WordPress/WordPress-Coding-Standards/issues/1763

Exemplu de cod valid

<? php / ** * Docblock de fisiere. * / nume de spatiu Prefix \ Admin \ Domain_URL \ Sub_Domain \ Event; utilizare …

Invalid O rezolutie pe trackerul de erori (si in general obisnuita in dezvoltarea de software, uneori notabug ) care indica faptul ca biletul nu este un bug, este o solicitare de asistenta sau este in general invalid. exemple de cod

<? php / ** * Docblock de fisiere. * / namespace Prefix \ / * Aici vine spatiul de nume real * / Admin \ DomainURL \ SubDomain \ Event; folositi … <? php / ** * Fileblock. * / nume spatiu Foo {// Cod. } spatiul de nume {// Cod. }

Utilizare in WordPress Core

Dupa cum s-a mentionat anterior, introducerea spatiilor de nume in WordPress Core va trebui sa fie un efort concertat, cu gandire atenta la implicatiile asupra arhitecturii in ansamblu.

In prezent, nu exista o cronologie pentru introducerea spatiilor de nume in WordPress Core.

Utilizare in pluginuri si teme

Utilizarea spatiilor de nume in pluginuri si teme este incurajata cu tarie. Este o modalitate excelenta de a prefixa o multime de coduri pentru a preveni denumirea conflictelor cu alte plugin-uri, teme si / sau WordPress Core.

Va rugam sa faceti o colectie de bloguri P2 la make.wordpress.org, care sunt gazduirea unui numar de grupuri de participanti, inclusiv dezvoltarea de baza (make / core, fost „wpdevel”), grupul de lucru UI (make / ui), traducatori (make / polyglots), recenzorii temei (make / theme), resurse pentru autorii de pluginuri (make / plugins) si grupul de lucru pentru accesibilitate (make / accessibility). asigurati-va ca utilizati un prefix unic si suficient de lung pentru spatii de nume pentru a preveni conflictele. In general, folosirea unui prefix al spatiului de nume de-a lungul liniilor Vendor \ Packagename este o idee buna.

Si, desi nu este nou, acesta poate fi, de asemenea, un moment potrivit pentru a va aminti ca utilizarea wp sau WordPress ca prefix nu este permisa (indiferent de caz).

// Corect. namespace My_Awesome_Plugin \ Admin; // Incorect. spatiul de nume MAP \ Admin;

Retineti, de asemenea, ca spatiul de nume nu are efect asupra variabilelor declarate in afara functiilor / claselor, constante declarate cu constructe native definite () sau non-PHP, cum ar fi numele de carlig utilizate in WordPress.

Acestea trebuie sa fie prefixate individual.

Importati instructiuni de utilizare

Standarde propuse:

Instructiunile de utilizare a importului ar trebui sa fie in partea de sus a unui fisier si ar trebui sa urmeze direct declaratia (optionala) a spatiului de nume.
Instructiunile de utilizare a importului ar trebui sa fie ordonate dupa tipul: primele instructiuni de utilizare a importurilor pentru clase, interfete si trasaturi, instructiunile de utilizare a importului pentru functii si, in sfarsit, instructiunile de utilizare a importurilor pentru constante.
In prezent nu sunt stabilite reguli pentru comandarea declaratiilor de utilizare a importurilor de acelasi tip. Aceasta va fi revizuita ulterior.
Ar trebui sa existe exact o linie goala inainte de prima declaratie de utilizare a importului de fiecare tip si cel putin o linie goala dupa ultima declaratie de utilizare a importului.
Utilizarea, functia, const si ca cuvinte cheie ar trebui sa fie mai mici.
Ar trebui sa existe exact un spatiu dupa fiecare cuvant cheie.
Denumirile dintr-o declaratie de utilizare a importului nu ar trebui sa inceapa cu o reversare principala \.
Toate numele din declaratiile de utilizare a importului trebuie sa fie complet calificate dupa natura, astfel incat o \ la inceput este redundanta.
Nu trebuie sa existe spatiu alb sau comentarii in partea de nume a unei declaratii de utilizare.
Numele de alias ar trebui sa respecte conventiile de denumire WordPress existente pentru nume de clasa / functie / constante.
Setati un alias numai atunci cand utilizati un nume diferit.
Adica acest lucru nu este permis: folositi My \ Project \ ClassName ca ClassName.

Nota: intrucat aceste nume sunt sensibile la litere mari si minuscule in PHP, aliasul la acelasi nume intr-un caz diferit intra sub aceasta regula si este interzis.
Cand utilizati declaratii de utilizare in grup:
1. Ar trebui sa existe o declaratie pentru fiecare tip – constructe OO (clase / interfete / trasaturi), functii, constante. Diferitele tipuri nu trebuie combinate intr-o declaratie de utilizare a unui grup.
2. Nu trebuie sa existe niciun spatiu intre separatorul spatiului de nume si bretonul bucla de deschidere pentru utilizarea grupului.
3. Braul ondulat de deschidere ar trebui sa fie ultimul element de cod al liniei.
4. Fiecare sub-declaratie trebuie sa fie una singura o linie si ar trebui sa fie indentata o fila din cuvantul cheie al declaratiei de utilizare.
5. Cand este posibil (PHP 7.2+), ultima declaratie ar trebui sa fie urmata de o virgula.
  Aceasta nu va fi aplicata pana cand cerinta PHP minima nu va fi ridicata la PHP 7.2.
6. Braul ondulat de inchidere ar trebui sa fie pe o linie de la sine, fara linie (linii) goale inainte.
7. Braul ondulat de inchidere trebuie sa fie indentat la fel ca cuvantul cheie de utilizare.

In acest moment, nu sunt definite (inca) standarde atunci cand trebuie sa fie utilizata o declaratie de utilizare a importului si cand sa folosesti un nume complet calificat in linie. Liniile directoare in acest sens pot fi adaugate ulterior.

Exemplu de cod valid

<? php / ** * Bloc doc documente. * / namespace WordPress \ subnamespace; utilizati Unele \ Nume spatiu \ Clasa_A; utilizati Unele \ Nume spatiu \ Class_C ca Aliased_Class_C; utilizati unele functii \ Nume spatiu \ {Class_D, Class_E ca Aliased_Class_E,} utilizati functia Some \ Nume spatiu \ functie_a; utilizati functia Some \ Nume spatiu \ functie_b ca aliased_functie; use const Some \ Nume spatiu \ CONSTANT_A; use const Some \ namespace \ CONSTANT_D ca ALIASED_CONSTANT; // Restul codului

Exemplu de cod nevalid

<? php / ** * Bloc doc documente. * / namespace WordPress \ subnamespace; utilizati Unele \ Nume spatiu \ / * comentariu * / Clasa_A; use const Some \ Nume spatiu \ CONSTANT_A; utilizati functia Some \ Nume spatiu \ functie_a; folosi \ Some \ Nume \ Nume \ Clasa_C ca aliased_class_c; utilizati Unele \ Nume spatii \ {Class_D, Class_E ca Aliased_Class_E} utilizati Furnizor \ Pachet \ {functie functie_a, functie functie_b, Clasa_C, const CONSTANT_NAME}; clasa Foo {// Cod. } folosi const \ Some \ Nume \ CONSTANT_D ca Aliased_constant; Utilizati functia Some \ Nume spatiu \ functie_b ca functie de aliased_Functie; // Restul codului

Utilizare in WordPress Core

In timp ce declaratiile de utilizare a importului pot fi deja utilizate in WordPress Core, pentru moment este foarte descurajata.

Instructiunile de utilizare a importurilor sunt cele mai utile atunci cand sunt combinate cu spatii de nume si o implementare de incarcare automata a clasei. Intrucat niciunul dintre acestea nu exista in prezent pentru WordPress Core si discutiile despre acest lucru sunt in desfasurare, renuntarea la adaugarea declaratiilor de utilizare a importului la WordPress Core este alegerea sanatoasa deocamdata.

Notite importante:

Adaugarea unei declaratii de utilizare nu incarca automat orice este importat. Inca trebuie sa incarcati fisierul care contine clasa / functia / constanta cu o instructiune require / include inainte de a utiliza codul importat.
Instructiunile de utilizare a importului nu au niciun efect asupra numelor de clasa, functii sau constante.
Instructiunile de utilizare a grupului nu pot fi utilizate in WordPress Core pana cand versiunea minima PHP a fost ridicata la PHP 7.0.
Raspunsurile la virgule in declaratiile de utilizare a grupului nu pot fi utilizate in WordPress Core pana cand versiunea minima PHP a fost ridicata la PHP 7.2.

Nume complet calificate in cod inline

Standarde propuse:

Cand utilizati un nume complet sau partial calificat, nu este permis niciun spatiu alb sau comentarii in cadrul numelui.

Exemplu de cod

// Corect. $ foo = new \ Vanzator \ Domeniu \ Foo (); $ rezultat = namespace \ nume_functie (); // Incorect. $ foo = new \ Vendor // Sursa: dependenta externa. \ Domeniu \ Foo (); $ rezultat = namespace \ nume_functie ();

Utilizare in WordPress Core

Pana la introducerea spatiilor de nume, nu este necesara introducerea utilizarii de nume complet calificate in coduri inline in WordPress Core.

Trasaturi si interfete

Standarde propuse pentru declaratii de trasatura / interfata:

Numele de trasaturi si de interfata ar trebui sa utilizeze cuvinte majuscule separate prin scoruri, la fel ca numele de clasa. Orice acronime ar trebui sa fie majuscule.
Cuvantul „Trasatura” nu este necesar intr-un nume de trasatura, dar nici nu va fi interzis.

Cuvantul „Interfata” nu este necesar intr-un nume de interfata, dar nici nu va fi interzis.
Numele de fisiere de trasatura ar trebui sa se bazeze pe numele de trasatura cu caracteristica pre-pre-transmisa si scrierile din numele de trasatura inlocuite cu cratime.
Acelasi lucru este valabil si pentru numele fisierelor de interfata, in cazul in care numele ar trebui sa se bazeze pe numele interfetei cu interfata predefinita, iar scrierile din numele interfetei sa fie inlocuite cu cratime.

Exemplu: pentru o trasatura numita Form_Field_Generator, fisierul ar trebui numit trait-form-field-generator.php.

Pentru orice altceva, se aplica aceleasi reguli de formatare deja existente pentru declaratiile de clasa.

Standarde propuse pentru formatarea declaratiilor de utilizare a trasaturilor:

Instructiunile de utilizare a trasaturii ar trebui sa fie in varful unei clase.
Instructiunile de utilizare a trasaturii ar trebui sa aiba exact o linie goala inainte de prima instructiune de utilizare si cel putin o linie goala dupa, cu exceptia unei clase care contine doar o instructiune de utilizare a trasaturii, caz in care linia goala dupa poate fi omisa.
Comentariile / documentele direct peste o declaratie de utilizare a trasaturilor vor fi considerate ca apartinand declaratiei, iar linia goala va fi aplicata deasupra acesteia.
Utilizarea, in loc de sau ca cuvinte cheie trebuie sa fie cu litere mici.
Trebuie sa existe exact un spatiu intre cuvantul cheie de utilizare si numele trasaturii.
Atunci cand grupati mai multe trasaturi intr-o instructiune de utilizare, nu ar trebui sa existe niciun spatiu intre un nume de trasatura si virgula si exact un spatiu intre virgula si urmatorul nume de trasatura.
Cand utilizati statementof sau ca instructiuni:
1. Trebuie sa existe exact un spatiu inainte si dupa fiecare dintre aceste cuvinte cheie.
2. Pentru instructiunile de utilizare cu o singura linie, trebuie sa existe exact un spatiu intre ultimul nume de trasatura si bretonul ondulat de deschidere si exact un spatiu intre bretonul ondulat de deschidere si inceputul instructiunii anexate.
  De asemenea, trebuie sa existe exact un spatiu intre semicolonul de la sfarsitul enuntului inchis si bretonul ondulat de inchidere si bretonul de bucla de inchidere ar trebui sa fie ultimul element de cod de pe linie.
3. Pentru instructiunile de utilizare pe mai multe linii, trebuie sa existe exact un spatiu intre ultimul nume de trasatura si bretonul ondulat de deschidere si o noua linie dupa bretonul ondulat.
  Braul ondulat de inchidere ar trebui sa fie pe o linie de la sine, fara linie (linii) goale inainte.
  
  Braul de inchidere trebuie sa fie indentat la fel ca cuvantul cheie de utilizare.
4. Cand utilizati multipleofof sau ca declaratii grupate in acolade, instructiunea trebuie sa devina o instructiune de utilizare a mai multor linii, iar fiecare dintre instructiunile de tip “sau” trebuie sa fie pe o linie de la sine, indentata exact o fila de la cuvantul cheie de utilizare.

Exemplu de cod

// Corect. class Foo {// Comentariile de mai sus o declaratie de utilizare vor fi considerate documentatie pentru instructiune. folositi BarTrait; utilizati FooTrait, BazingaTrait {BarTrait :: nume_ metoda in loc de FooTrait; BazingaTrait :: nume_ metoda ca bazinga_method; } utilizati LoopyTrait {mancati ca protejat; } public $ baz = true; …} clasa Foo {folositi BarTrait; } // Incorect. clasa Foo {folositi BarTrait; utilizati FooTrait, BazingaTrait {BarTrait :: nume_ metoda in loc de FooTrait; BazingaTrait :: nume_ metoda ca bazinga_method; }; public $ baz = adevarat; …}

Utilizare in WordPress Core

Interfatele ar putea fi folosite anterior in WordPress Core si sunt incurajate sa fie utilizate pentru a clarifica interfata publica a seturilor de clase conexe.

Trasaturile pot fi utilizate in WordPress Core, desi ar trebui sa fie evaluat cu atentie in fiecare instanta individuala daca utilizarea unei trasaturi este o decizie corecta din punct de vedere arhitectural.

Declaratii de tip

Standarde propuse:

Declaratiile de tip trebuie sa aiba exact un spatiu inainte si dupa tip.
In cazul unei declaratii de functii cu mai multe linii, inainte de declaratia de tip, ar trebui utilizata o noua linie + liniuta corespunzatoare.
Operatorul de nulitate este considerat ca facand parte din declaratia de tip si nu ar trebui sa existe niciun spatiu intre acest operator si tipul real.
Declaratiile de tip bazate pe cuvinte cheie ar trebui sa utilizeze minuscule.
Declaratiile de tip bazate pe numele clasei / interfetei ar trebui sa utilizeze cazul numelui clasei / interfetei asa cum este declarat.

Si in special pentru declaratiile de tip retur:

Nu trebuie sa existe niciun spatiu intre paranteza de inchidere a declaratiei de functie si punerea in punte a unui tip de intoarcere.

Aceste reguli se aplica tuturor structurilor care permit declaratii de tip: functii, inchideri, conditii de captura, precum si functiile sagetii PHP 7.4 si proprietatile tastate.

Exemplu de cod

// Corect. function foo (Class_Name $ param_a,? string $ param_b, apelabil $ param_c):? \ Class_Name {// Faceti ceva. } bara de functii (Interface_Name $ param_a,? int $ param_b, bool $ param_c):? \ Class_Name {// Faceti ceva. } // Incorect. function baz (Class_Name $ param_a,? Float $ param_b, CALLABLE $ param_c):? \ Class_Name {// Faceti ceva. }

Utilizare in WordPress Core

Cu toate ca rara, exista si declaratii de tip bazate pe nume de clasa si interfata in WordPress Core.

Adaugarea declaratiilor de tip la functiile existente de baza ale WordPress Core trebuie facuta cu mare atentie .

Semnatura functiei pentru orice functie (metoda) care poate fi supraincarcata de pluginuri sau teme nu trebuie sa fie atinsa .

Aceasta include toate metodele existente de clasa publica si protejata si orice functii declarate conditionat (conectabile) in spatiul de nume global.

Acest lucru lasa, deocamdata, doar functii declarate neconditionat in spatiul de nume global, metodele clasei private si codul nou introduse ca fiind candidati pentru adaugarea declaratiilor de tip.

Pentru acestia, adaugarea declaratiilor de tip de parametru bazate pe nume de clasa si de interfata, in cazul in care tipul de parametru se asteapta doar la un tip si ar permite simplificarea codului existent / nou si este incurajat.

Folosirea de cuvinte cheie a tabloului in declaratii de tip este puternic descurajata deocamdata, deoarece, cel mai adesea, ar fi mai bine sa folositi iterabil pentru a permite o mai mare flexibilitate in implementare, iar acest cuvant cheie nu este inca disponibil pentru a fi utilizat in WordPress Core pana cand cerintele minime sunt majorate. la PHP 7.1.

Nota:

Declaratiile de tip scalar bool, int, float si string nu pot fi utilizate in WordPress Core pana cand versiunea PHP minima nu a fost ridicata la PHP 7.0.
Declaratiile de tip returnare nu pot fi utilizate pana cand versiunea minima PHP nu a fost ridicata la PHP 7.0.
Declaratiile de tip nullable nu pot fi utilizate pana cand versiunea minima PHP nu a fost ridicata la PHP 7.1.
Declaratiile de tip iterabil, nul si obiect nu pot fi utilizate pana cand versiunea PHP minima nu a fost ridicata la PHP 7.1, respectiv 7.2.
Declaratiile de tip de proprietate nu pot fi utilizate pana cand versiunea minima PHP nu a fost ridicata la PHP 7.4.

Declarati declaratii / dactilografiere stricta

Standarde propuse:

Ar trebui sa existe exact o linie goala deasupra declaratiei declarate si cel putin o linie goala mai jos.
Cuvintele cheie utilizate – declarati, tipuri stricte, capuse si codificare – ar trebui sa fie minuscule.
Nu trebuie sa existe niciun spatiu intre cuvantul cheie declarat si paranteza deschisa.
Nu trebuie sa existe niciun spatiu in interiorul parantezelor.
Nu trebuie sa existe niciun spatiu de o parte si de alta a = operatorului utilizat in declaratiile declarate.
Declaratiile care utilizeaza sintaxa blocului de breton ondulat sunt permise numai pentru capuse. Pentru declaratii declarate folosind sintaxa blocului cu breton ondulat:
1. Ar trebui sa existe exact un spatiu intre paranteza de inchidere si bretonul de deschidere, iar bucla de deschidere ar trebui sa fie ultimul element de cod de pe linie.
2. Continutul blocului ar trebui sa fie indentat dintr-o fila din indentarea cuvantului cheie declarare.
3. Si bratura creta de inchidere ar trebui sa fie pe o linie de la sine, fara nici o linie goala deasupra ei si cel putin o linie goala sub ea.

Nota: aceste standarde sunt diferite de cele utilizate pentru apelurile functionale. Retineti ca declararea nu este o functie.

Exemplu de cod

// Corect. <? php / ** * Bloc doc documente. * / declara (strict_tipuri = 1); folosi … declara (capuse = 1) {// Faceti ceva. } // Incorect. <? php / ** * Bloc doc documente. * / declara (strict_tipuri = 1); utilizare …

Utilizare in WordPress Core

In acest moment, nu trebuie utilizat tipul strict.

Este o caracteristica PHP 7.0+, dar chiar si atunci cand WordPress Core ar obtine o cerinta minima PHP 7.0, implementarea tiparirii stricte va avea nevoie de o atentie atenta, deoarece o multime de WordPress Core se bazeaza pe tipul liber al PHP, deci nu este ceva care sa fie intreprins usor si nu se afla pe ordinea de zi pentru viitorul previzibil.

Celelalte declaratii declarate, bifuri si codificare, pot fi utilizate in WordPress Core, dupa caz.

Constanta de clasa ::

Standarde propuse:

Nu trebuie sa existe niciun spatiu intre :: clasa si numele clasei precedente la care se aplica.
Nu trebuie sa existe niciun spatiu intre dublul punct si cuvantul cheie de clasa.
Cuvantul cheie al clasei ar trebui sa fie cu litere mici.

Exemplu de cod

// Corect. add_action (‘nume_actiune’, tablou (clasa mea_clasa :: clasa, ‘nume_ metoda’)); // Incorect. add_action (‘nume_actiune’, tablou (My_Class :: CLASS, ‘name_ method’));

Utilizare in WordPress Core

Constanta de clasa :: poate fi folosita liber in WordPress Core.

Inlocuirea utilizarilor existente ale __CLASS__ cu self :: class si get_called_class () cu static :: class, dupa caz, este incurajata.

operatorii

Spread operator …

Standarde propuse:

Inainte de operatorul de raspandire, ar trebui sa existe un spatiu, sau o noua linie + indentare corespunzatoare.
Nu trebuie sa existe spatiu intre operatorul de raspandire si apelul la variabila / functie la care se aplica.
Atunci cand combinati operatorul de raspandire cu operatorul de referinta, nu trebuie sa existe niciun spatiu intre ei.

Problema WPCS deschisa conexa: https://github.com/WordPress/WordPress-Coding-Standards/issues/1762

Exemplu de cod

// Corect. function foo (& … $ spread) {bar (… $ spread); bar (array (… $ foo), … array_values ($ keyed_array)); } // Incorect. functie prost (& … $ spread) {bar (… $ spread); bar ([… $ foo], …

/ * comentariu * / array_values ($ keyed_array)); }

Utilizare in WordPress Core

Operatorul de raspandire pentru ambalarea argumentelor in declaratiile de functii si dezambalarea acestora in apelurile functionale a fost introdus in WordPress Core in WP 5.3 si poate fi utilizat liber cand este cazul.

Daca doriti sa aflati mai multe detalii despre momentul in care operatorul de raspandire nu poate / nu poate fi utilizat, citirea notelor de implementare din biletul Trac asociat este foarte recomandata.

Operatorul de raspandire nu poate fi folosit pentru a despacheta matricile pana cand versiunea minima PHP a fost ridicata la PHP 7.4.

instanceof, pow , pow este egal cu =, nava spatiala <=>, nul coalesce ?? iar nul coalesce este egal cu ??

Se aplica normele deja existente cu privire la operatori:

Puneti intotdeauna spatii pe ambele parti ale operatorilor logici, de comparatie, siruri si alocari.

Operatorii de egalitate in blocuri de cod ar trebui sa fie aliniat pentru lizibilitate.

Utilizare in WordPress Core

Instanta ar putea fi deja folosita in WordPress Core si este incurajata utilizarea acestui operator in loc de apelul functiei catre is_a (), deoarece este mai performanta.

Operatorii pow ** si pow sunt egali cu ** = operatorii pot fi folositi liber in WordPress Core si au fost introdusi in WP 5.3.

Nava spatiala <=>, coalesce nula ?? si null coalesce egal = operatorii nu pot fi folositi in WordPress Core pana cand versiunea PHP minima nu a fost ridicata la PHP 7.0 (nava spatiala si nul coalesce) sau PHP 7.4 (nul coalesce egal).

Reguli suplimentare noi

O definitie asemanatoare clasei pe fisier

Standarde propuse:

Ar trebui sa existe o singura definitie asemanatoare clasei (class / trait / interfata) pe fiecare fisier.

Aceasta a fost deja o buna practica de ceva vreme si acum va fi oficializata.

Inrudite deschise WPCS PR: https://github.com/WordPress/WordPress-Coding-Standards/pull/1802

Vizibilitatea ar trebui sa fie intotdeauna declarata

Standarde propuse:

Pentru toate constructiile care ii permit (proprietati, metode), vizibilitatea trebuie declarata explicit.
Utilizarea cuvantului cheie var pentru declaratiile de proprietate nu este permisa.

Aceasta a fost deja o buna practica de ceva vreme si acum va fi oficializata.

Exemplu de cod

// Corect. clasa Foo {public $ foo; protected function bar () {}} // Incorect. clasa Foo {var $ foo; bara de functii () {}}

Utilizare in WordPress Core

In cazul in care lipsesc modificatori de vizibilitate in codul Core WordPress, acestia ar trebui sa fie stabiliti pe public, astfel incat sa nu incalce compatibilitatea inapoi.

Vizibilitatea pentru constantele de clasa nu poate fi utilizata in WordPress Core pana cand versiunea minima PHP a fost ridicata la PHP 7.1 (si nu va fi aplicata pana la acel moment).

Comanda de modificare a proprietatii si a metodei

Standarde propuse:

Cand utilizati mai multi modificatori pentru o declaratie de proprietate sau metoda, comanda trebuie sa fie urmatoarea:
1. In primul rand, cuvantul cheie abstract sau optional final.
2. Urmeaza un cuvant cheie vizibilitate.
3. In sfarsit, cuvantul cheie static optional.

Aceasta a fost deja o buna practica de ceva vreme si acum va fi oficializata.

Exemplu de cod

// Corect. abstract class Foo {public static $ foo; bara de functii statice protejate abstract (); } // Incorect. abstract class Foo {static public $ foo; bara de functii protejate abstracte static (); }

Instantarea obiectului

Standarde propuse:

Atunci cand instantanezi o noua instanta a unui obiect, trebuie sa folositi intotdeauna paranteza, chiar si atunci cand nu este strict necesar.
Nu trebuie sa existe niciun spatiu intre numele clasei care este initiat si paranteza de deschidere.
Nu este permisa atribuirea valorii de retur a unei instante de obiect prin referinta.
Noua de referinta nu a fost acceptata de PHP de mult timp acum.

Aceasta a fost deja o buna practica de ceva vreme si acum va fi oficializata.

Exemplu de cod

// Corect. $ foo = new Foo (); $ anon = new class () {…}; $ instanta = static nou (); // Incorect. $ foo = & nou Foo; $ foo = new Foo ();

Functia bretele de inchidere

Standarde propuse:

Nu trebuie sa existe o linie goala intre continutul unei functii si dispozitivul de inchidere a functiei.

Exemplu de cod

// Corect. function foo () {// Faceti ceva. } // Incorect. function foo () {// Faceti ceva. }

Inlantuirea metodei

Standarde propuse:

Atunci cand metoda de inlantuire apeleaza pe mai multe linii, liniile ulterioare ar trebui sa fie indentate cel putin o fila de la inceputul instructiunii si sa nu aiba mai mult de o diferenta de liniuta intre fila intre indentarea liniei curente si indentarea liniei anterioare.
Sageata trebuie plasata pe aceeasi linie cu apelul metodelor ulterioare.

Exemplu de cod

// Corect. $ someObject -> doSomething () -> doSomethingElse (); $ someObject -> startSomething () -> someOtherFunc (23, 42) -> endSomething (); // Incorect. $ someObject -> startSomething () -> someOtherFunc (23, 42) -> endSomething ();

Include / Necesita

Standarde propuse:

Nu se vor folosi paranteze pentru includerea [_once] si pentru a necesita declaratii [_once].
Deoarece include [_once] si necesita [_once] sunt constructii de limbaj, nu au nevoie de paranteze in jurul caii.
Ar trebui sa existe exact un spatiu intre include [_once] si necesita cuvantul cheie [_once] si inceputul caii.
Este recomandat sa folositi require [_once] pentru includeri neconditionate.
Cand utilizati include [_once] PHP va arunca un avertisment atunci cand fisierul nu este gasit, dar va continua executia, care va duce aproape sigur la alte erori / avertizari / notificari aruncate daca aplicatia dvs. depinde de fisierul disponibil, ceea ce poate duce la securitate. scurgeri. Din acest motiv, a cere [_once] este, in general, alegerea mai buna, deoarece va arunca o eroare fatala daca fisierul nu poate fi gasit.

Aceasta a fost deja o buna practica de ceva vreme si acum va fi oficializata.

Inrudite deschise WPCS PR: https://github.com/WordPress/WordPress-Coding-Standards/pull/1862

Exemplu de cod

// Corect. require_once ABSPATH. ‘Filename.php’; // Incorect. include_once (ABSPATH. ‘nume de fisier.php’);

Operatori de crestere / decrementare

Standarde propuse:

Nu trebuie sa existe niciun spatiu intre un operator de incrementare / decrementare si variabila la care se aplica.
Pre-incrementarea / decrementarea ar trebui sa fie favorizata de post-increment / decrement pentru declaratii de sine statatoare.
„Pre” va intra / decret si apoi va reveni, „post” se va intoarce si apoi in / decret.

Utilizarea versiunii „pre” este putin mai performanta si poate preveni viitoarele erori atunci cand codul este mutat.

Problema WPCS deschisa conexa: https://github.com/WordPress/WordPress-Coding-Standards/issues/1511

Exemplu de cod

// Corect. for ($ i = 0; $ i <10; $ i ++) {} – $ a; // Incorect. for ($ i = 0; $ i <10; $ i ++) {} $ a–;

Constante magice

Standarde propuse:

Constantele magice native PHP __…__ ar trebui sa fie majuscule atunci cand sunt utilizate.

Exemplu de cod

// Corect. add_action (‘nume_actiune’, tablou (__CLASS__, ‘nume_ metoda’)); require_once __DIR__. ‘/Relative-path/file-name.php’; // Incorect. add_action (‘nume_actiune’, tablou (__class__, ‘nume_ metoda’)); require_once __dIr__. ‘/Relative-path/file-name.php’;

Porunci Shell

Standarde propuse:

Utilizarea operatorului backtick nu este permisa.

Aceasta a fost deja o buna practica de ceva vreme si acum va fi oficializata.

Conditii complexe ale structurii de control

O declaratie a structurii de control cu mai multe conditii poate face ca liniile foarte lungi sa faca codul mai greu de citit.

Se incurajeaza (dar nu se impune) ca aceste conditii indelungate sa fie impartite in mai multe linii.

Cand o declaratie de conditie lunga este impartita pe mai multe linii, sunt propuse urmatoarele (noi) reguli pe langa regulile existente pentru formatarea structurii de control:

Prima conditie ar trebui sa fie pe aceeasi linie cu cuvantul cheie al structurii de control.
Paranteza de inchidere pentru structura de control ar trebui sa fie pe o noua linie, indentata la fel ca cuvantul cheie al structurii de control si urmata de un spatiu si braul bucla de deschidere a structurii de control.
La impartirea conditiilor in mai multe linii, operatorii booleani / logici care separa instructiunile ar trebui sa fie intotdeauna plasate la inceputul liniei noi.
Acest lucru creeaza seturi de schimbari mai mici si imbunatateste lizibilitatea.

Nota: chiar si in conditiile raspandite pe mai multe linii, mai multe conditii pe fiecare linie vor fi permise, atat timp cat grupul de conditii are sens.

Exemplu de cod

// Este permisa o singura linie. if (function_call ($ a, $ b, $ c) === false && (isset ($ d, $ e, $ f) && function_call ($ d, $ e, $ f) === true) && function_call ( $ g, $ h, $ i) === false) {// Faceti ceva. } // Formatarea corecta la utilizarea mai multor linii: if (functie_call ($ a, $ b, $ c) === false && (isset ($ d, $ e, $ f) && functie_call ($ d, $ e, $ f) === true) && function_call ($ g, $ h, $ i) === false) {// Faceti ceva. } // Formatare incorecta atunci cand utilizati mai multe linii: if (functie_call ($ a, $ b, $ c) === false && (isset ($ d, $ e, $ f) && function_call ($ d, $ e, $ f) === true) && function_call ($ g, $ h, $ i) === false) {// Faceti ceva. }

Parere

Feedbackul cu privire la standardele propuse aici este binevenit in comentarii.

Daca exista alte constructii PHP si caracteristici de limbaj pentru care doriti sa vedeti definite standardele de codare, va rugam sa deschideti o problema in depozitul GitHub pentru standardele de codare WordPress.

Solicitare amabila: in timp ce imi dau seama ca pozitia existenta privind interzicerea sintaxei scurte a tabloului este un subiect fierbinte pentru unii oameni, va rugam sa nu poluati discutiile despre standardele care sunt propuse in prezent prin redeschiderea acestei discutii in comentarii .

Sintaxa scurta a tabloului va fi revizuita ulterior, dar nu face parte din propunerea actuala. Va multumim anticipat pentru intelegere.

Postari anterioare pe acest subiect:

https://make.wordpress.org/core/2019/07/12/php-coding-standards-changes/
https://make.wordpress.org/core/2019/03/26/coding-standards-updates-for-php-5-6/

Obiective: multumiri gratioase mergeti la @dingo_d, @garyj, @netweb, @nielsdeblaauw, @pento, @schlessera si @SergeyBiryukov pentru revizuirea acestui post inainte de publicare.

#modernizewp, #codingstandards, #php, #wpcs

Reguli pentru constructii PHP moderne

Declaratii ale spatiului de nume

Exemplu de cod valid

Invalid O rezolutie pe trackerul de erori (si in general obisnuita in dezvoltarea de software, uneori notabug ) care indica faptul ca biletul nu este un bug, este o solicitare de asistenta sau este in general invalid. exemple de cod

Utilizare in WordPress Core

Utilizare in pluginuri si teme

Importati instructiuni de utilizare

Exemplu de cod valid

Exemplu de cod nevalid

Utilizare in WordPress Core

Nume complet calificate in cod inline

Exemplu de cod

Utilizare in WordPress Core

Trasaturi si interfete

Exemplu de cod

Utilizare in WordPress Core

Declaratii de tip

Exemplu de cod

Utilizare in WordPress Core

Declarati declaratii / dactilografiere stricta

Exemplu de cod

Utilizare in WordPress Core

Constanta de clasa ::

Exemplu de cod

Utilizare in WordPress Core

operatorii

Spread operator …

Exemplu de cod

Utilizare in WordPress Core

instanceof, pow **, pow este egal cu ** =, nava spatiala <=>, nul coalesce ?? iar nul coalesce este egal cu ??

Utilizare in WordPress Core

Reguli suplimentare noi

O definitie asemanatoare clasei pe fisier

Vizibilitatea ar trebui sa fie intotdeauna declarata

Exemplu de cod

Utilizare in WordPress Core

Comanda de modificare a proprietatii si a metodei

Exemplu de cod

Instantarea obiectului

Exemplu de cod

Functia bretele de inchidere

Exemplu de cod

Inlantuirea metodei

Exemplu de cod

Include / Necesita

Exemplu de cod

Operatori de crestere / decrementare

Exemplu de cod

Constante magice

Exemplu de cod

Porunci Shell

Conditii complexe ale structurii de control

Exemplu de cod

Parere

Populare

instanceof, pow , pow este egal cu =, nava spatiala <=>, nul coalesce ?? iar nul coalesce este egal cu ??