Konwencja nazewnictwa – standardy projektowe

Konwencje nazewnicze w programowaniu to ustalone zasady dotyczące nazwania zmiennych, funkcji, klas i innych elementów w kodzie programu. Przestrzeganie jednolitych konwencji ułatwia czytanie i zrozumienie kodu oraz współpracę między programistami.

W celu ułatwienia wspólnej pracy na różnego rodzaju projektach rekomendujemy zastosowanie jednolitej konwencji dla poszczególnych języków.

Projekty JavaScript

Użyj nazw klas zgodnych z konwencją camelCase: nazywanie klas za pomocą camelCase jest popularną konwencją w ekosystemie React. Zaczynaj nazwy klas małą literą i używaj wielkich liter, aby oddzielić słowa. Na przykład: myComponent, headerSection, buttonContainer, itd.

Unikaj nazw klas o ogólnych lub potencjalnie kolizyjnych nazwach: Staraj się używać nazw klas, które są unikalne dla danego komponentu lub modułu. Unikaj ogólnych nazw, takich jak style, container, box, które mogą prowadzić do konfliktów z innymi elementami lub stylami.

Zastosuj konwencję nazewnictwa BEM (Block Element Modifier): BEM to popularna metoda nazewnictwa klas w CSS, która pomaga w tworzeniu modułowych i reużywalnych styli. Możesz zastosować tę konwencję również w Next.js. Na przykład: myComponent, myComponent__innerElement, myComponent--modifier

Unikaj zbyt długich i skomplikowanych nazw klas: Staraj się utrzymać nazwy klas zwięzłe i czytelne. Unikaj zbyt długich lub skomplikowanych nazw, które utrudniają czytanie i utrzymanie kodu

Wybierz nazwy klas związane z funkcjonalnością: Nazwy klas powinny być związane z funkcjonalnością komponentu. Staraj się używać nazw, które jasno opisują, co dany komponent robi lub reprezentuje. Na przykład: navbar, loginForm, productCard, itd.

Organizuj komponenty w logiczne foldery, aby ułatwić nawigację. Nazwy folderów zapisuj z małymi literami (components/, containers/, utils/).

Pliki konfiguracyjne projektu, takie jak pliki webpack czy babel, zazwyczaj mają nazwy z dużych liter i używają podkreśleń (webpack.config.js, babel.config.js.).

Projekty PHP

Używaj zmiennych zgodnych z konwencją camelCase. Rozpoczynaj nazwy od małej litery, a każde kolejne słowo zapisuj wielką literą. Unikaj krótkich i enigmatycznych nazw na rzecz bardziej opisowych, które łatwiej zidentyfikować.

$userId = 1;
$userName = "John Doe";

Nazwy funkcji powinny również być zapisane w notacji camelCase, zaczynając od małej litery. Wybieraj nazwy, które jednoznacznie opisują zadanie funkcji.

function calculateTotal($price, $quantity) {
    return $price * $quantity;
}

Nazwy klas stosuj w notacji StudlyCaps (Pascal Case), zaczynając od wielkiej litery dla każdego słowa. Staraj się, aby nazwa klasy jasno wskazywała na jej przeznaczenie.

class UserProfile {
    // ...
}

Nazwy plików powinny odzwierciedlać nazwę głównej klasy w pliku. Ułatwi to znalezienie odpowiedniego kodu w strukturze projektu.

UserProfile.php

Nazwy stałych zapisuj wielkimi literami i oddzielaj słowa podkreśleniem. Stałe są przydatne, gdy wartość nie powinna się zmieniać w trakcie działania programu.

define('MAX_LENGTH', 100);

Metody w klasach również powinny korzystać z notacji camelCase. Nazwy metod powinny jednoznacznie wskazywać na ich funkcję w kontekście danej klasy.

class ShoppingCart {
    public function calculateTotal() {
        // ...
    }
}

Przestrzenie nazw pomagają w organizacji kodu. Używaj notacji StudlyCaps dla nazw przestrzeni nazw, aby utrzymać spójność.

namespace App\Controllers;

Projekty HTML, JS, SCSS

Dla prostych projektów opartych jedynie na html, js oraz scss stosujemy BEM

BEM (Block Element Modifier) to konwencja nazewnicza i metodologia organizacji kodu w projektach front-endowych.

Block (Blok): Bloki to główne komponenty strony, reprezentujące niezależne, wielokrotnie występujące elementy. Nazwy bloków zapisuje się w notacji kebab-case.

https://getbem.com/naming

<div class="header-section">
    <!-- Zawartość nagłówka -->
    <h1 class="header-section__title">Nagłówek</h1>
    <button class="header-section__button header-section__button--primary">Click me</button>
</div>

<section class="article-container">
    <article class="article-container__item">
        <h2 class="article-container__title">Artykuł</h2>
    </article>
</section>

W przykładowym kodzie powyżej, header-section i article-container są blokami.

Element (Element): Elementy to składowe bloków, reprezentujące ich części składowe. Nazwy elementów zapisuje się z użyciem dwóch podkreślników __.

<div class="header-section">
    <h1 class="header-section__title">Nagłówek</h1>
    <button class="header-section__button header-section__button--primary">Click me</button>
</div>

<section class="article-container">
    <article class="article-container__item">
        <h2 class="article-container__title">Artykuł</h2>
    </article>
</section>

Tutaj, title i button są elementami bloku header-section, a item i title są elementami bloku article-container.

Modifier (Modyfikator): Modyfikatory to warianty bloków lub elementów, zmieniające ich wygląd lub zachowanie. Nazwy modyfikatorów zapisuje się z użyciem dwóch myślników --.

<button class="header-section__button header-section__button--primary">Click me</button>

Tutaj, primary to modyfikator przycisku w bloku header-section__button.

JavaScript

JavaScript:

W JavaScript stosuj konwencję camelCase do nazw zmiennych, funkcji i metod.

let userName = "John Doe";

function calculateTotal(price, quantity) {
    return price * quantity;
}

document.getElementById('myButton').addEventListener('click', function() {
    // Logika obsługi kliknięcia
});

Nazwy zmiennych (userName), funkcji (calculateTotal) i metod (addEventListener) są nazywane zgodnie z konwencją camelCase.

SCSS (z użyciem BEM):

W SCSS stosuj konwencję BEM do klas, używając odpowiednich separatorów __ dla elementów i -- dla modyfikatorów.

.header-section {
    padding: 20px;

    &__title {
        font-size: 24px;
    }

    &__button {
        background-color: $primary-color;

        &--primary {
            color: white;
        }
    }
}

.article-container {
    padding: 20px;

    &__item {
        &:hover {
            background-color: #eee;
        }

        &__title {
            font-size: $font-size + 4px;
        }
    }
}

Bloki (header-section, article-container), elementy (__title, __button) i modyfikatory (--primary) są nazywane zgodnie z konwencją BEM.

Zagnieżdżaj style, aby zorganizować reguły dotyczące konkretnego elementu lub jego dzieci. Unikaj zagnieżdżania zbyt głęboko, aby uniknąć zbyt skomplikowanej struktury.

.article-container {
    padding: 20px;

    &:hover {
        background-color: #eee;
    }

    .article-title {
        font-size: $font-size + 4px;
    }
}