Technologia

Konwencje nazewnictwa w React: jak pisać czysty i spójny kod?

Grafika przedstawiająca nałożone na siebie napisy camelCase i PascalCase, ilustrująca różnice w konwencjach nazewnictwa w kodzie

6 min czytania

Web Dev

Wstęp

Konwencje nazewnictwa to zbiór zasad dotyczących wyboru nazw dla zmiennych, funkcji, plików czy folderów. Są one kluczowe dla utrzymania czytelności projektu i ułatwiają komunikację między programistami, którzy dzięki nim posługują się wspólnym językiem i terminologią.

W tym artykule podzielę się z Tobą wiedzą na temat stosowania konwencji nazewnictwa w kodzie i projektach React.

Najpopularniejsze konwencje

Przyjrzyjmy się najpopularniejszym konwencjom nazewnictwa stosowanym przez programistów, ze szczególnym uwzględnieniem tych używanych w projektach React.

camelCase

camelCase to konwencja, w której pierwsze słowo w nazwie zaczyna się małą literą, a każde kolejne wielką. Na przykład: handleClick, useState, currentAccountBalance.

Zastosowanie:

Zmienne
Funkcje
Hooki
Pliki i foldery niekomponentowe w React

Przykład w kodzie JSJavaScript

1const myName = 'Steve';
2
3const sayHello = (userName) => {
4	console.log(`Hello ${userName}!`);
5}
6
7sayHello(myName);

Przykład w strukturze plikówMarkdown

1hooks
2├── useAppDispatch.ts
3└── useAppSelector.ts

PascalCase

PascalCase, znany również jako "CapitalCamelCase", to konwencja podobna do camelCase, ale każde słowo zaczyna się wielką literą. Na przykład: LoginScreen, Button, App.

Zastosowanie:

Komponenty React
Pliki i foldery komponentów React
Klasy
Typy

Przykład w strukturze plikówMarkdown

1Button
2├── index.jsx
3└── Button.module.scss

Przykład komponentu Button w kodzieJSX

1// index.jsx
2export default function Button({ children }) {
3  return <button>{children}</button>;
4}

UPPER_CASE

UPPER_CASE, znany również jako "CONSTANT_CASE" lub "SCREAM_CASE", to konwencja, w której wszystkie litery w nazwie są wielkie. Na przykład: FIRST_NAME, API_URL, APP_VERSION.

Zastosowanie:

Stałe
Wartości enum

Przykłady w kodzie TSTypeScript

1const PI = 3.14;
2const API_URL = "https://example.com/api";

Przykład w kodzie TSTypeScript

1enum RoutePath {
2	DASHBOARD = '/',
3	BLOG = '/blog',
4	PRIVACY_POLICY = '/privacy-policy',
5	TERMS_OF_SERVICE = '/terms-of-service'
6}

kebab-case

kebab-case, znany również jako "dash-case", to konwencja, w której słowa w nazwie są oddzielone myślnikami. Na przykład: button-primary, main-heading, gallery-item.

Zastosowanie:

Klasy CSS
Atrybuty HTML
Pliki i foldery
Adresy URL

Przykład w kodzie HTMLHTML

1<ul class="site-nav">
2  <li class="site-nav-item"><a href="#">Sklep</a></li>
3  <li class="site-nav-item"><a href="#">Blog</a></li>
4  <li class="site-nav-item"><a href="#">Kontakt</a></li>
5</ul>

snake_case

snake_case to konwencja, w której słowa w nazwie są oddzielone podkreślnikami. Na przykład: last_name, annual_earnings, total_products_found.

Zastosowanie:

Zmienne i funkcje w niektórych językach (Python, Ruby, SQL)
Rzadko spotykany w aplikacjach React

Przykład w kodzie SQLSQL

1CREATE TABLE customers (
2  customer_id INT PRIMARY KEY,
3  first_name VARCHAR(50),
4  last_name VARCHAR(50),
5  email VARCHAR(100)
6);

Konwencje specyficzne dla React

Oprócz ogólnych zasad nazewnictwa, istnieją wytyczne specjalne dla projektów React.

Nazwy komponentów

Komponenty React powinny być pisane w PascalCase. Używaj rozszerzenia .jsx lub .tsx dla plików z komponentami React. Ułatwia to rozróżnić pliki z komponentami React od innych plików oraz pozwala odblokować dodatkowe możliwości w edytorze kodu.

Przykład w strukturze plikówMarkdown

1src
2└── components
3   ├── layout
4   │   ├── Header
5   │   │   ├── index.tsx
6   │   │   └── Header.module.scss
7   │   └── Footer
8   │       ├── index.tsx
9   │       └── Footer.module.scss
10   └── TodoList
11       ├── index.tsx
12       ├── TodoList.module.scss
13       └── components
14           ├── TodoItem
15           │   ├── index.tsx
16           │   └── TodoItem.module.scss
17           └── AddTodoForm
18               ├── index.tsx
19               └── AddTodoForm.module.scss

Hooki

Nazwy hooków powinny zaczynać się od słowa use i być pisane w camelCase. Na przykład: useEffect, useState, useFetch.

Przykład w kodzie JSXJSX

1const [count, setCount] = useState(0);
2
3useEffect(() => {
4	document.title = `You clicked ${count} times`;
5}, [count]);

Funkcje "handlery"

Funkcje obsługi zdarzeń powinny zaczynać się od słowa "handle", na przykład handleClick, handleChange, handleLoad. Ułatwia to czytelność, zrozumienie kodu oraz pomaga przy refaktoryzacji kodu, ponieważ można łatwo znaleźć wszystkie funkcje handlerów poprzez wyszukanie słowa "handle".

Przykład w kodzie JSXJSX

1const handleInputChange = (event) => {
2  const { name, value } = event.target;
3  setFormValues((prev) => ({ ...prev, [name]: value }));
4};
5
6const handleToggleModalVisibility = () => {
7  setIsModalOpen((prev) => !prev);
8}

Style

W React można używać różnych metod do definiowania stylów. Oto zalecane konwencje dla różnych podejść:

Przykłady

1. Inline — camelCase

JSX

1<button style={{ backgroundColor: 'blue', color: 'white' }}>Tekst</button>

2. Zwyczajny CSS — kebab-case

JSX

1.button-primary {
2  background-color: blue;
3  color: white;
4}
5
6<button className="button-primary">Tekst</button>

3. CSS Modules — camelCase

JSX

1.buttonPrimary {
2  background-color: blue;
3  color: white;
4}
5
6import styles from './style.css';
7
8<button className={styles.buttonPrimary}>Tekst</button>

4. CSS-in-JS — camelCase

JSX

1// biblioteka styled-components
2import styled from 'styled-components';
3
4const Button = styled.button` background-color: blue; color: white; `;
5
6<Button>Tekst</Button>

Wymuszanie stosowania konwencji z ESLint i TypeScript

Możesz użyć reguły ESLint @typescript-eslint/naming-convention do wymuszenia odpowiednich konwencji nazewnictwa w projekcie TypeScript. Oto przykładowa konfiguracja:

.eslintrcJavaScript

1{
2  "rules": {
3    "@typescript-eslint/naming-convention": [
4      "error",
5      {
6        "selector": "default",
7        "format": ["camelCase"]
8      },
9      {
10        "selector": "variable",
11        "format": ["camelCase", "PascalCase", "UPPER_CASE"]
12      },
13      {
14        "selector": "function",
15        "format": ["camelCase", "PascalCase"]
16      },
17      {
18        "selector": "typeLike",
19        "format": ["PascalCase"]
20      },
21      {
22        "selector": "enumMember",
23        "format": ["UPPER_CASE"]
24      }
25    ]
26  }
27}

Pełną dokumentację znajdziesz na stronie naming-convention | typescript-eslint.

Podsumowanie

Konwencje nazewnictwa są kluczowym elementem pracy zespołowej, ułatwiającym komunikację i współpracę. Warto znać różne opcje i wybrać te, które najlepiej odpowiadają potrzebom zespołu. Dla dużych zespołów dobrym rozwiązaniem może być stworzenie reguł ESLint wymuszających stosowanie przyjętych zasad w projekcie.

Pamiętaj, że najważniejsza jest spójność w całym projekcie. Wybrane konwencje powinny być zrozumiałe i oczywiste dla wszystkich członków zespołu, co przyczyni się do tworzenia bardziej czytelnego i łatwiejszego w utrzymaniu kodu 😉.