Jakie są standardy kodowania w Drupalu i jak je używać w codziennej pracy?
Standaryzacja ma pozytywny wpływ na każdą firmę. W branży oprogramowania istnieją pewne standardy kodowania, które są potrzebne do pomyślnego tworzenia oprogramowania. Standardy kodowania to zestaw reguł i dobrych praktyk, dzięki którym kod jest bardziej czytelny i łatwy w rozwijaniu. W tym artykule przedstawimy, jakie standardy są używane przy tworzeniu projektów w Drupalu. Pokażemy podstawowe aspekty, na które warto zwracać uwagę oraz narzędzia usprawniające pracę.
Standardy kodowania w Drupalu
Społeczność Drupala definiuje zestaw standardów kodowania i najlepszych praktyk, których należy przestrzegać podczas pisania kodu. Częściowo bazują one na standardach kodowania PEAR. Wszystkie nowo zaproponowane przez społeczność standardy kodowania są najpierw omawiane w projekcie Coding Standards.
Standardy kodowania w Drupalu są niezależne od wersji Drupala, w której aktualnie pracujemy. Cały nowy kod powinien być zgodny z aktualnymi zasadami. Pełną informację o standardach kodowania w Drupalu można znaleźć na oficjalnej stronie Drupala.
Tablica
Tablice powinny być sformatowane przy użyciu krótkiej składni ze spacjami oddzielającymi każdy element po przecinku. Należy dodawać spacje przed i po operatorze przypisania “=>”.
$some_array = ['hello', 'world', 'foo' => 'bar'];
Jeśli deklaracja tablicy przekracza 80 znaków, należy ją rozbić na kilka linii.
$form['title'] = [
'#type' => 'textfield',
'#title' => t('Title'),
'#size' => 60,
'#maxlength' => 128,
'#description' => t('The title of your node.'),
];
Zwróć uwagę na przecinek w ostatniej linii - to nie jest błąd. W ten sposób można zapobiec błędom w przyszłości przy dodawaniu nowych elementów tablicy.
Uwaga! Krótka składnia jest dostępna w PHP od wersji 5.4. W starszych wersjach należy używać długiej składni.
If else
Struktura if else wygląda tak jak na przykładzie poniżej. Zwróć uwagę na rozmieszczenie nawiasów, spacji i nawiasów klamrowych. Instrukcje sterujące powinny mieć jedną spację między warunkiem i nawiasem otwierającym.
if (condition1 || condition2) {
action1;
}
elseif (condition3 && condition4) {
action2;
}
else {
defaultaction;
}
Uwaga! Nigdy nie używaj else if. Zamiast tego możesz używać elseif.
Switch
Zawsze używaj okrągłych nawiasów w instrukcjach sterujących, nawet kiedy są one technicznie opcjonalne, jak na przykład przy instrukcji sterującej switch. Zwiększa to czytelność kodu.
switch (condition) {
case 1:
action1;
break;
case 2:
action2;
break;
default:
defaultaction;
}
Do while
Poniżej pokazujemy przykład dla instrukcji sterującej do while. Między do i nawiasem otwierającym należy dodać spację. Warunek musi być w tej samej linii, co nawias zamykający instrukcję, oddzielony spacją od niego.
do {
actions;
} while ($condition);
Długość linii kodu
Każda linia kodu nie powinna być dłuższa niż 80 znaków. Wyjątkiem może być deklaracja funkcji, klasy lub zmiennej z bardzo długą nazwą.
Dzielenie klauzul warunkowych
Warunki nie powinny przekraczać jednej linii. Drupal zachęca nas do wyniesienia wartości warunku do zmiennej dla podwyższenia czytelności. Poniżej jest przykład, jak należy przerabiać zbyt długie linie warunkowe.
Tak jest źle:
if ((isset($key) && !empty($user->uid) && $key == $user->uid) || (isset($user->cache) ? $user->cache : '') == ip_address() || isset($value) && $value >= time())) {
...
}
Tak jest dobrze:
$is_valid_user = isset($key) && !empty($user->uid) && $key == $user->uid;
// IP must match the cache to prevent session spoofing.
$is_valid_cache = isset($user->cache) ? $user->cache == ip_address() : FALSE;
// Alternatively, if the request query parameter is in the future, then it
// is always valid, because the galaxy will implode and collapse anyway.
$is_valid_query = $is_valid_cache || (isset($value) && $value >= time());
if ($is_valid_user || $is_valid_query) {
...
}
Przykładowa funkcja
function funstuff_system($field) {
$system["description"] = t("This module inserts funny text into posts randomly.");
return $system[$field];
}
Argumenty z domyślnymi wartościami zawsze muszą być na końcu. Natomiast funkcje anonimowe powinny mieć spację między „funkcją” a jej parametrami, jak w poniższym przykładzie:
array_map(function ($item) use ($id) {
return $item[$id];
}, $items);
Standardy kodowania JavaScript w Drupalu
Zawsze dodawaj swoje skrypty JS, korzystając z Drupal.behavior. Nazwy funkcji powinny zaczynać się od nazwy modułu lub motywu deklarującego funkcję, aby uniknąć kolizji nazw.
Drupal.behaviors.tableDrag = function (context) {
Object.keys(Drupal.settings.tableDrag).forEach(function (base) {
$('#' + base).once('tabledrag', addBehavior);
});
};
Standardy kodowania CSS w Drupalu
Poniżej znajdziesz kilka zasad, które pomogą Ci w prawidłowym kodowaniu CSS.
Unikaj polegania na strukturze HTML
CSS powinien określać wygląd elementu w dowolnym miejscu i miejscu, w którym się pojawia. Nigdy nie używaj HTML selektorów.
BEM
Dobrą praktyką w pisaniu styli w Drupalu jest stosowanie się do metodyki BEM. Takie pisanie kodu CSS zapobiega wielokrotnemu zagnieżdżaniu oraz poleganiu na strukturze znaczników i nadmiernie ogólnych nazwach klas. Metodyka dzieli wszystkie elementy na trzy kategorię:
- Bloki - są to najczęściej pojedyncze komponenty, na przykład nawigacja. W kodzie wygląda to jak pojedyncza klasa, np. .navigation.
- Elementy - czyli części podrzędne bloku, na przykład link w nawigacji. Nazwa elementu powinna być oddzielona od nazwy bloku dwoma podkreśleniam, np. .navigation__link, .navigation__item.
- Modyfikatory - specyficzne warianty bloków i elementów. Nazwa modyfikatora powinna być odzielona od podstawy dwoma myślnikami, przykładowo: .navigation–dark, .navigation__link–active.
Standardy kodowania - Drupal i Twig
Wszystkie standardy kodowania w Twigu, silniku szablonów dla PHP, są opisane na oficjalnej stronie dokumentacji Twiga.
Wyrażenia
Wyrażenia w Twigu są bardzo podobne do wyrażeń w PHP. Najczęściej są używane do sprawdzania, czy zmienna istnieje, deklarowania pętli i nowych zmiennych w szablonach.
Sprawdzanie, czy zmienna jest dostępna do drukowania:
{% if foo %}
<div>{{ foo }}</div>
{% endif %}
Pętla:
{% for key, value in items %}
<div class="{{ key }}">{{ value }}</div>
{% endfor %}
Deklaracja nowych zmiennych:
{% set list = ['Alice', 'Bob'] %}
{% set text = ':person is a Twig fan'|t({':person': list[0] }) %}
Filtry
Niektóre z najpopularniejszych funkcji Drupala, takie jak t i url, zostały udostępnione w szablonach Twig jako filtry. Są one wyzwalane za pomocą znaku potoku | .
<div class="preview-text-wrapper">
{{ 'Original'|t }}
</div>
Jak używać standardów kodowania w Drupalu na co dzień?
Istnieją narzędzia pomagające formatować kod do postaci zgodnej ze standardami. Przedstawimy tu kilka takich narzędzi, które stosujemy podczas Drupal developmentu.
- Code Sniffer - narzędzie ułatwiające pisanie kodu dla Drupala lub jego modułów. Może wykrywać i automatycznie naprawiać standardowe błędy kodowania i formatowania.
- Moduł Drupala Coder - zintegrowany z Code Snifferem pomaga naprawiać błędy w standardzie kodowania.
- CSSComb - narzędzie do sortowania i formatowania kodu CSS.
Używając narzędzi zintegrowanych z IDE, programista nie musi znać wszystkich standardów kodowania na pamięć i jest zabezpieczony przed, na przykład, wkradnięciem się jakiejś zbędnej spacji czy złego tabulatora. Dowie się też, jeśli nastąpią jakieś nowe zmiany w konwencji kodowania.
Podsumowując, bardzo ważne jest, aby zespół programistów trzymał się odpowiednich konwencji i standardów kodowania, które będą kierować nim podczas tworzenia oprogramowania. Pomoże to utrzymać jakość kodu i skróci czas spędzany przez nowych deweloperów na próbie zrozumienia złożonej bazy kodu.
