Standardy kodowania: coś do powąchania

Opublikowany: 2021-07-19

Niektóre pytania pojawiły się już od czasów tworzenia oprogramowania. Czy należy wcinać tabulatory czy spacje? Czy standardy kodowania są naprawdę takie ważne? Czy naprawdę muszę tracić czas na przestrzeganie arbitralnych zasad?

Odpowiednio odpowiedzi na te pytania to: zakładki (oczywiście), tak (mniej oczywiście) i nie (w pewnym sensie).

Kodowanie PHP

Znaczenie standardów zostało szczegółowo omówione przez innych, więc nie będę tu wchodzić w szczegóły, ale sedno tego jest takie: spójność wewnętrzna jest pożądana w ramach danego projektu, ponieważ poprawia czytelność, ogranicza niespodzianki i może przyczynić się do zwiększenia solidność kodu.

Nie musisz „marnować czasu” na trzymanie się standardów, ponieważ istnieją sposoby na automatyczne stosowanie tych standardów!

Omówię tutaj sposób szybkiego i łatwego skonfigurowania samodzielnego narzędzia PHP Codesniffer (PHPCS) dla projektów WordPress. Umożliwi to:

  • Sporządź raport na temat zgodności standardów w swoim kodzie
  • Automatycznie rozwiązuj różnorodne problemy związane ze zgodnością

W poniższych przykładach będziemy wdrażać standardy WordPress.

Instalowanie

Wymagania wstępne:

  • Dostęp terminalowy (użytkownicy systemu Windows mogą odnieść sukces z Bash dla systemu Windows, ale nie jest to testowane)
  • Menedżer pakietów kompozytorskich

Chociaż można zainstalować sam PHPCS, domyślnie nie obsługuje on WordPressa. W tym celu zainstalujemy skrótowo nazwane WordPress Coding Standards (WPCS).

Najpierw przejdź do miejsca, w którym chcesz zainstalować WPCS do użytku globalnego.

 $ > cd /ścieżka/do/gdziekolwiek

Zainstaluj pakiet z kompozytorem.

 $ > kompozytor utwórz-projekt wp-coding-standards/wpcs --no-dev

W tym momencie moglibyśmy zanurkować i zacząć używać WPCS, ale za każdym razem, gdy uruchamiamy polecenie, należy ustawić kilka flag. Dla wygody skonfigurujmy kilka aliasów.

Otwórz .profile ze swojego katalogu domowego w swoim ulubionym edytorze (lub utwórz go, jeśli nie istnieje) i dodaj:

 # Standardy kodowania WP
export PATH=$PATH:"/ścieżka/do/gdziekolwiek/wszt/dostawca/pojemnik"
alias wpcs='phpcs --standard=WordPress --extensions=php
alias wpcbf='phpcbf --standard=WordPress --extensions=php

Dodaliśmy tutaj dwa aliasy – jeden dla phpcs (który znajduje i wyświetla błędy zgodności) i jeden dla phpcbf (który automatycznie naprawia różne problemy znalezione przez phpcs). Dodatkowe opcje są następujące:

–standard=WordPress – stosuje standardy WordPress (ustawiane w WPCS)

–extensions=php – docelowe tylko pliki PHP (PHPCS domyślnie obsługuje PHP, CSS i JS)

Uruchom ponownie Terminal (lub source .profile ), a WPCS będzie gotowy do sniffowania Twojego kodu!

Wąchanie

Aby wygenerować raport sniff dotyczący pliku, uruchom następujące polecenie:

 $ > wpcs /ścieżka/do/twojego/php/projektu/pliku.php

Spowoduje to wyświetlenie raportu w terminalu. Alternatywnie możesz wyprowadzić to do pliku:

 $ > wpcs /ścieżka/do/twojego/php/projektu/pliku.php > output.txt

Raport wąchania

Twój wynik sniff WPCS będzie wyglądał mniej więcej tak:

Raport PHP Codesniffer

Jest tu sporo informacji, ale są one dość przejrzyście ułożone. Przyjrzyjmy się, co mamy:

  • Docelowy plik
  • Podsumowanie liczby znalezionych błędów/ostrzeżeń oraz liczby wierszy, których dotyczy problem
  • Lista znalezionych problemów wraz z poziomami ważności i opisami
  • Wskazanie, ile problemów phpcbf może rozwiązać automatycznie (w zasadzie wszystkie problemy z [x])

Jak można się było spodziewać, PHPCS nie jest w stanie wyjaśnić wszystkiego. Nie będzie dokonywać założeń dotyczących wyboru interpunkcji w komentarzach i niektórych rodzajów formatowania kodu, ale może poradzić sobie z wieloma różnymi problemami.

Miłym bonusem jest to, że reguły WordPress pozwalają PHPCS wykryć problemy specyficzne dla WordPressa, w tym potencjalne niewłaściwe użycie funkcji.

Ustalenie

Automatyczne rozwiązywanie problemów nie może być prostsze:

 $ > wpcbf /ścieżka/do/twojego/php/projektu/pliku.php

Wyświetlane jest krótkie podsumowanie:

Wyjście narzędzia do naprawy kodu PHP

Wszelkie pozostałe błędy musiałyby zostać naprawione ręcznie, ale zwykle okaże się, że większość problemów została rozwiązana.

Zasady niestandardowe

Możesz także chcieć dostosować zestaw reguł, wykluczyć niektóre katalogi w swoim projekcie i tak dalej. Dokumentacja zestawu reguł z adnotacjami PHPCS zawiera przykłady wszystkich zmian, które możesz wprowadzić, ale ogólnie mówiąc, wystarczy:

  1. Utwórz plik zestawu reguł
  2. Odwołaj się do niego w poleceniu PHPCS

Oto przykład pliku zestawu reguł:

 <?xml version="1.0"?>
<ruleset name="Standardy kodowania WordPress">
    <description>Dostosowane standardy WordPress.</description>
    <rule ref="WordPress">
        <exclude name="Generic.Formatting.MultipleStatementAlignment.NotSameWarning"/>
    </rule>
    <exclude-pattern>*/bin/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
    <exclude-pattern>*/testy/*</exclude-pattern>
</ruleset>

W przykładzie zrobiliśmy co następuje:

  • Odwołuje się do zestawu reguł WordPress (z WPCS)
  • Wykluczono regułę
  • Wykluczono niektóre katalogi

Plik zestawu reguł można umieścić w dowolnym katalogu, z którego wywołujesz WPCS (projekt, motyw lub root wtyczki jest zwykle rozsądny) i można się do niego odwoływać za pomocą flagi. Zaktualizuj flagę –standard w swoim .profile, na przykład:

 # Standardy kodowania WP
export PATH=$PATH:"/ścieżka/do/gdziekolwiek/wszt/dostawca/pojemnik"
alias wpcs='phpcs --standard=codesniffer.ruleset.xml --extensions=php
alias wpcbf='phpcbf --standard=codesniffer.ruleset.xml --extensions=php

Aby sprawdzić, które reguły są oznaczane podczas uruchamiania WPCS, po prostu uruchom go z flagą -s w następujący sposób:

 $ > wpcs -s /ścieżka/do/twojego/php/projektu/pliku.php

Co następne?

Powyższy przewodnik umożliwi Ci przeprowadzanie kontroli zgodności ze standardami ad hoc w projekcie WordPress, ale jeśli chcesz zintegrować go ze standardowym cyklem rozwoju, następnym logicznym krokiem jest automatyzacja.

Rozważ zintegrowanie PHPCS z mechanizmem uruchamiającym zadania, takim jak gulp lub grunt (moduły PHPCS są dostępne dla obu) lub w inny sposób zintegrowanie go z potokiem kompilacji CI/CD.

Aby uzyskać pomoc w tworzeniu i projektowaniu stron internetowych, skontaktuj się z nami już dziś.

Jeśli potrzebujesz pomocy, nie wahaj się z nami skontaktować.