Standardy programowania w Drupalu - kluczowe zasady i praktyki

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.

1. Otwierający nawias klamrowy powinien znajdować się w tym samym wierszu co otwierająca instrukcja, poprzedzony jedną spacją.
2. 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.'),
 ];

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 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.

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:

1. Dodawanie tylko jednej spacji po rozpoczęciu delimitera (“{{“,” {%”,” {#”) i przed zakończeniem delimitera (“}}”,” %}”,” #”})
2. Dodawanie jednej spacji przed i po operatorach porównania, matematycznych, logicznych, ~, is, in, oraz operatorze ternarnym
3. Dodawanie jednej spacji w tablicach i haszach
4. Niedodawanie spacji po otwartym nawiasie i przed zamkniętym nawiasem w wyrażeniach
5. Nieumieszczanie spacji przed i po delimiterach ciągu znaków
6. Niedodawanie spacji do operatorów takich jak “|”,” .”,” ..”,” []”
7. Unikanie spacji przed i po nawiasach użytych do wywołań filtrów i funkcji
8. Używanie zmiennych z małych liter i oddzielanie je podkreśleniem
9. Używanie tego samego wcięcia, co język docelowy renderowanego szablonu