Standardy programowania w Drupalu - kluczowe zasady i praktyki
W kontekście tworzenia stron internetowych przestrzeganie pewnych standardów programowania staje się kluczowym elementem jakości, bezpieczeństwa i skalowalności projektów. We wpisie przybliżymy istotę tych standardów, pokazując praktyki, które pozwalają na efektywną implementację funkcji na platformie Drupal.
![Najlepsze praktyki programowania w Drupalu Standardy programowania - Drupal](https://files.smartbees.pl/sites/default/files/styles/sm_552_px/public/2024-07/standardy-programowania-w-drupalu.jpg.webp?itok=gMk0TB4g)
Czym są standardy programowania w Drupalu?
Czym są standardy programowania w Drupalu?
Standardy programowania w Drupalu odnoszą się do zestawu zasad, konwencji i praktyk, które określają sposób tworzenia kodu. Stanowią wytyczne dotyczące:
- struktury,
- formatowania,
- dokumentowania kodu.
Mają na celu ułatwienie współpracy między programistami oraz zapewnienie czytelności i spójności kodu źródłowego. W skrócie, standardy programowania w Drupalu są wyznacznikiem jakości i profesjonalizmu w procesie tworzenia aplikacji internetowych opartych na tym systemie.
Podstawowe zasady implementacji standardów programowania
Podstawowe zasady implementacji standardów programowania
Podstawowe zasady obejmują przede wszystkim stosowanie jednolitego formatowania kodu, zawierającego odpowiednie wcięcia, nawiasy czy odstępy. Ważne jest również właściwe dokumentowanie kodu poprzez komentarze, które opisują jego działanie oraz znaczenie poszczególnych fragmentów.
Ponadto kluczową zasadą jest unikanie bezpośrednich zmian w plikach core'owych systemu, co zapewnia łatwiejsze aktualizacje i utrzymanie platformy. Przykładem może być zastosowanie hook'ów do modyfikacji zachowania systemu bez ingerencji w jego podstawowe pliki.
Standardy programowania w różnych językach programowania
Standardy programowania w różnych językach programowania
Standardy programowania w Drupalu są stałe, czyli niezależne od wersji Drupala, na której aktualnie pracujesz. Nowy kod powinien być zgodny z najnowszymi zasadami, aby zapewnić spójność i czytelność. Szczegółowe informacje na temat standardów kodowania w Drupalu można znaleźć na oficjalnej stronie internetowej Drupala.
Standardy programowania PHP w Drupalu
Standardy kodowania w PHP opierają się głównie na standardach kodowania PEAR. Oto najważniejsze z nich:
1. Używanie wcięcia o szerokości 2 spacji, bez stosowania tabulatorów.
2. Linie nie powinny zawierać białych znaków na końcu.
3. Wszystkie bloki na początku pliku PHP powinny być oddzielone pustą linią.
Nagłówek pliku może wyglądać następująco:
<?php namespace This\Is\The\Namespace; use Drupal\foo\Bar; /** * Provides examples. */ class ExampleClassName {
4. Pojedyncza linia kodu nie powinna zawierać więcej niż 80 znaków, za wyjątkiem linii zawierających dłuższe nazwy funkcji, definicji funkcji/klas, deklaracji zmiennych itp.
5. Nazwy funkcji należy pisać małymi literami, a słowa powinny być oddzielone podkreśleniem. Funkcje natomiast powinny zawierać nazwę grupy/modułu jako przedrostek, aby uniknąć kolizji nazw między modułami.
6. Zmienne powinny być nazywane małymi literami, a słowa powinny być oddzielone albo dużymi literami (na przykład: $lowerCamelCase), albo podkreśleniem (przykład: $snake_case). Radzimy w tej kwestii zachować spójność i nie mieszać nazewnictwa zmiennych camelCase i snake_case wewnątrz pliku.
Operatory
Wszystkie operatory binarne, takie jak +, -, =, !=, ==, > itp. powinny mieć spację przed i po operatorze. Na przykład przypisanie powinno być sformatowane jako $foo = $bar;
Operatory jednoargumentowe, takie jak ++ nie powinny mieć spacji między operatorem a zmienną lub liczbą, na której działają.
Instrukcje warunkowe i pętle
Instrukcje sterujące powinny mieć jedną spację między słowem kluczowym a nawiasem otwierającym, aby odróżnić je od wywołań funkcji.
Zawsze używaj nawiasów klamrowych w instrukcjach sterujących, nawet kiedy są opcjonalne. Stosowanie ich zwiększa czytelność oraz zmniejsza prawdopodobieństwo wystąpienia błędów podczas dodawania nowych linii.
- Otwierający nawias klamrowy powinien znajdować się w tym samym wierszu co otwierająca instrukcja, poprzedzony jedną spacją.
- Zamykający nawias klamrowy powinien być dodawany w oddzielnej linii i mieć wcięcie do tego samego poziomu co otwierająca instrukcja.
Przykładowa struktura instrukcji if else:
if (condition1 || condition2) { action1; } elseif (condition3 && condition4) { action2; } else { defaultaction; }
Przykładowa struktura instrukcji switch:
switch (condition) { case 1: action1; break; case 2: action2; break; default: defaultaction; }
Przykładowa struktura pętli do while:
do { actions; } while ($condition);
Wywołania funkcji
Funkcje powinny być wywoływane bez spacji między nazwą funkcji, nawiasem otwierającym i pierwszym parametrem, bez spacji między przecinkami i każdym parametrem oraz bez spacji między ostatnim parametrem, nawiasem zamykającym i średnikiem. Oto przykład:
$var = foo($bar, $baz, $quux);
Tablice
Tablice deklarujemy przy użyciu krótkiej składni ze spacjami oddzielającymi każdy element po przecinku. Jeśli występuje operator przypisania => należy dodać spację przed operatorem oraz po nim, np.
$array = ['hello', 'world', 'foo' => 'bar'];
Jeśli deklaracja tablicy przekracza 80 znaków, należy ją rozbić na kilka linii, np.
$form['title'] = [ '#type' => 'textfield', '#title' => t('Title'), '#size' => 60, '#maxlength' => 128, '#description' => t('The title of your node.'), ];
Standardy programowania JavaScript w Drupalu
Zobacz najważniejsze zasady, jeśli chodzi o standardy kodowania w języku JavaScript w Drupalu.
Drupal Behaviors
W większości przypadków kod JS powinien być zawarty w Drupal Behaviors - jest to obiekt w JavaScript, który Drupal inicjalizuje po załadowaniu strony i po każdym wywołaniu AJAX w DOM (Document Object Model). Dzięki nim integracja JavaScript w witrynach i projektach opartych o Drupal staje się lepsza i wygodniejsza.
Wcięcia
Podobnie jak w przypadku języka PHP, należy używać wcięcia o szerokości 2 spacji, bez stosowania tabulatorów, a linie nie powinny zawierać białych znaków na końcu.
Średniki
JavaScript pozwala na opcjonalne „wstawianie średnika", jednak standardy Drupala tego nie tolerują. Wszystkie instrukcje (z wyjątkiem instrukcji function, if, switch, try, while) muszą być zakończone średnikiem (;), a wartości zwracane muszą rozpoczynać się na tej samej linii co słowo kluczowe return.
Nazewnictwo
Zmienne i funkcje wielowyrazowe, które nie są stałymi ani konstruktorami, powinny być nazwane zgodnie z konwencją lowerCamelCase.
W przypadku gdy zmienna zawiera obiekt jQuery, zmienna musi zaczynać się od znaku dolara ($):
var $form = $('#search-block-form'); var $inputs = $form.find('input');
Zmienne
Wszystkie zmienne muszą być zadeklarowane za pomocą var przed ich użyciem i powinny być deklarowane tylko raz, na początku funkcji.
Każda przypisana zmienna powinna być deklarowana w osobnej linii - również zmienne, które są jedynie deklarowane, ale nie otrzymują przypisanej wartości, np.
var anArray = []; var eventCallback = function () {}; var curTableDragSetting;
Funkcje
Nazwy funkcji powinny zaczynać się od nazwy modułu lub motywu deklarującego funkcję, aby uniknąć kolizji nazw:
Drupal.behaviors.myModuleTableDrag = function (context) { Object.keys(Drupal.settings.tableDrag).forEach(function (base) { $('#' + base).once('tabledrag', addBehavior); }); };
Tablice
Tablice powinny być formatowane z jedną spacją oddzielającą każdy element oraz operator przypisania:
var someArray = ['hello', 'world'];
Podobnie jak w przypadku języka PHP, jeśli deklaracja tablicy przekracza 80 znaków, należy ją rozbić na kilka linii.
Standardy programowania CSS w Drupalu
Standardy programowania CSS w Drupalu obejmują zalecenia dotyczące organizacji stylów, wykorzystania klas CSS oraz metodologii nazewnictwa, takiej jak BEM (Block Element Modifier).
Struktura BEM
BEM (Block Element Modifier) pomaga w utrzymaniu czytelności, spójności i skalowalności kodu CSS, szczególnie w dużych projektach. Jest oparta na trzech podstawowych pojęciach: Blok, Element i Modyfikator.
1. Blok jest niezależnym komponentem, który może być używany samodzielnie lub jako część większej struktury. To główny kontener, który zawiera wiele elementów w obrębie jednej funkcji. Bloki mają unikalne nazwy i reprezentują duże części strony internetowej, takie jak nagłówki, menu nawigacyjne, stopki, np.
.navbar { /* Style dla bloku navbar */ }
2. Element jest częścią bloku zależnym od niego. Nie powinien być używany samodzielnie poza kontekstem danego bloku. Elementy są zwykle oznaczone za pomocą klas wewnątrz bloku i używane do definiowania poszczególnych części, np.
.navbar__item { /* Style dla elementu item w bloku navbar */ }
3. Modyfikator jest dodatkową klasą, która zmienia wygląd, zachowanie bloku lub elementu. Pozwala to na elastyczność w stylizacji, zachowując jednocześnie spójność. Modyfikatory mogą zmieniać wielkość, kolor, ukrywać lub dodawać dodatkowe funkcje, np.
.navbar--dark { /* Modyfikator zmieniający styl navbar na ciemny */ } .navbar__item--active { /* Modyfikator wyróżniający aktywny element w navbarze */ }
Definiowanie komponentów w ich własnych plikach CSS
Najlepszą praktyką jest umieszczanie komponentów w ich własnych plikach CSS i ładowanie tylko wtedy, gdy jest to konieczne, poprzez zdefiniowanie ich we własnej bibliotece. Staraj się nie mieszać wielu komponentów w jednym pliku, aby zachować klarowność kodu i ułatwić jego zarządzanie.
Formatowanie CSS w Drupalu
Poniżej przedstawiamy kilka kluczowych zasad, które warto mieć na uwadze podczas formatowania CSS w Drupalu:
- używaj 2 spacji dla każdego poziomu wcięcia;
- deklaracje (pary właściwość/wartość) powinny być wcięte o jeden poziom względem selektora;
- na końcu linii nie może być żadnych białych znaków (spacji lub tabulatorów);
- wszystkie pliki tekstowe powinny kończyć się pojedynczą pustą linią;
- w deklaracji, nazwa właściwości powinna być bezpośrednio poprzedzona dwukropkiem, następnie pojedynczą spacją, a następnie wartością właściwości;
- na końcu wszystkich deklaracji należy umieścić średnik.
Standardy programowania - Twig
Twig jest szablonowym silnikiem używanym w Drupalu do generowania dynamicznych treści HTML. To język szablonów oparty na składni PHP, ale jest bezpieczniejszy i prostszy w użyciu. Najważniejsze aspekty dotyczące standardów programowania w twigu to:
- Dodawanie tylko jednej spacji po rozpoczęciu delimitera (“{{“,” {%”,” {#”) i przed zakończeniem delimitera (“}}”,” %}”,” #”})
- Dodawanie jednej spacji przed i po operatorach porównania, matematycznych, logicznych, ~, is, in, oraz operatorze ternarnym
- Dodawanie jednej spacji w tablicach i haszach
- Niedodawanie spacji po otwartym nawiasie i przed zamkniętym nawiasem w wyrażeniach
- Nieumieszczanie spacji przed i po delimiterach ciągu znaków
- Niedodawanie spacji do operatorów takich jak “|”,” .”,” ..”,” []”
- Unikanie spacji przed i po nawiasach użytych do wywołań filtrów i funkcji
- Używanie zmiennych z małych liter i oddzielanie je podkreśleniem
- Używanie tego samego wcięcia, co język docelowy renderowanego szablonu
Przydatne narzędzia do formatowania kodu według standardów
Przydatne narzędzia do formatowania kodu według standardów
Aby ułatwić proces utrzymania spójności i jakości kodu, istnieją różne narzędzia do formatowania kodu, które pomagają programistom w utrzymaniu zgodności z przyjętymi standardami oraz najlepszymi praktykami w danej dziedzinie. W tej sekcji przedstawimy 5 przydatnych narzędzi do formatowania kodu w językach PHP, JavaScript i CSS, które są często wykorzystywane podczas tworzenia stron internetowych.
- PHPCS (PHP CodeSniffer) to narzędzie, które pomaga w automatycznym sprawdzaniu zgodności z określonymi standardami kodu PHP. Można skonfigurować go do używania różnych zestawów zasad, w tym popularnych standardów takich jak PSR-2. PHP CodeSniffer analizuje kod źródłowy i zgłasza wszelkie naruszenia standardów.
- ESLint jest jednym z najpopularniejszych narzędzi do lintowania (analizy statycznej) kodu JavaScript. Pozwala programistom definiować niestandardowe reguły lintowania oraz wybierać z istniejących standardów takich jak Airbnb, Google czy StandardJS. ESLint sprawdza kod JavaScript pod kątem błędów, stylu i wydajności.
- Stylelint jest narzędziem do lintowania kodu CSS, które pomaga w utrzymaniu spójności i czystości stylów. Można skonfigurować go do stosowania różnych zestawów reguł, w tym popularnych standardów takich jak CSScomb, Sass Guidelines czy BEM (Block Element Modifier). Stylelint analizuje kod CSS pod kątem błędów, nadmiernych właściwości, nieprawidłowego formatowania i niezależności od przeglądarek.
- Twig CS Fixer - to narzędzie pomaga w automatyzacji procesu poprawiania i utrzymywania czystości kodu Twig poprzez dostosowanie go do ustalonych standardów programowania w Twigu.
- Coding standards Drupal - to narzędzie, które zostało stworzone przez nasz zespół. Zawiera rozszerzone konfiguracje innych narzędzi (np. PHP CodeSniffer, Coder, PHPStan czy też Twig CS Fixer) w celu utrzymania wysokiej jakości kodu zgodnego z ustalonymi standardami.
Podsumowanie
Podsumowanie
Przestrzeganie standardów programowania w Drupalu jest kluczowe dla utrzymania czystego, czytelnego i efektywnego kodu. Zastosowanie się do tych zasad nie tylko ułatwia współpracę w zespole programistycznym, ale także przyczynia się do poprawy wydajności i bezpieczeństwa witryny.