Повний гайд з угод про імена у веб-розробці

Повний гайд з угод про імена у веб-розробці

Повний гайд з угод про імена у веб-розробці

Чому іменування — це не просто дрібниці

Уявіть, що ви відкриваєте чужий код і бачите змінну d, функцію f() та клас usrMgr. Чи зрозуміло вам, що відбувається? Напевно, ні. А тепер уявіть currentDate, validateEmail() та UserManager. Різниця очевидна.

Правильне іменування — це не педантизм, а інвестиція в майбутнє вашого проєкту. Коли через півроку ви або ваші колеги читатимете код, хороші імена заощадять години розбирань та відлагодження.

Чотири золоті правила іменування

Перш ніж заглиблюватися в специфіку мов та технологій, запам’ятайте ці принципи:

1. Консистентність понад усе
Оберіть одну конвенцію та дотримуйтесь її у всьому проєкті. Краще посередня, але послідовна система, ніж ідеальна, але застосовувана від випадку до випадку.

2. Читабельність важливіша за стислість
getUserAuthenticationToken() краще, ніж getUsrAuthTkn(). Сучасні редактори коду мають автодоповнення — користуйтеся цим.

3. Імена повинні пояснювати призначення
Якщо вам потрібен коментар, щоб пояснити, що робить змінна або функція, то, ймовірно, ім’я обрано невдало.

4. Контекст має значення
У класі User метод getName() зрозумілий. У глобальній області краще використовувати getUserName().

Основні стилі іменування та де їх застосовувати

camelCase

Коли використовувати: JavaScript змінні, функції, методи

const firstName = 'John';
const isUserActive = true;
function calculateTotalPrice() { /* ... */ }

PascalCase

Коли використовувати: Класи, компоненти, типи, інтерфейси

class UserManager { /* ... */ }
interface UserData { /* ... */ }

kebab-case

Коли використовувати: Файли, папки, CSS класи, HTML атрибути

.user-profile { /* ... */ }

<div data-user-id="123">

snake_case

Коли використовувати: Бази даних, деякі константи

CREATE TABLE user_profiles (
  user_id INTEGER,
  created_at TIMESTAMP
);

SCREAMINGSNAKECASE

Коли використовувати: Глобальні константи, змінні оточення

const API_BASE_URL = 'https://api.example.com';
const MAX_RETRY_COUNT = 3;

JavaScript та Node.js: деталі, що мають значення

Булеві змінні — говоріть прямо

Використовуйте префікси, які роблять логічне значення очевидним:

// ✅ Відмінно
const isEnabled = true;
const hasPermission = false;
const canEdit = true;
const shouldUpdate = false;

// ❌ Уникайте
const enabled = true; // Незрозуміло, що це boolean
const permission = false; // Що саме false?

Функції — починайте з дієслова

Функція виконує дію, тому ім’я повинно це відображати:

// ✅ Зрозуміло, що відбувається
function getUser() { /* отримати */ }
function validateEmail() { /* перевірити */ }
function calculateTotal() { /* обчислити */ }
function fetchUserData() { /* завантажити */ }
function toggleVisibility() { /* перемкнути */ }

// ❌ Незрозумілі наміри
function user() { /* що робимо з користувачем? */ }
function email() { /* відправляємо? перевіряємо? */ }

Приватні методи — підкресліть приватність

class UserService {
  constructor() {
    this._privateProperty = 'secret';
  }

  _privateMethod() {
    // Старий стиль — префікс підкреслення
  }

  // Сучасний синтаксис
  #reallyPrivate = 'very secret';

  #privateMethod() {
    // Справжня приватність
  }
}

Організація файлів та проєктів

Структура Node.js проєкту

Добре організована структура проєкту — це половина успіху:

my-project/
├── src/
│   ├── controllers/
│   │   ├── user-controller.js
│   │   └── auth-controller.js
│   ├── services/
│   │   ├── user-service.js
│   │   └── email-service.js
│   ├── models/
│   │   ├── user-model.js
│   │   └── product-model.js
│   ├── utils/
│   │   ├── validation-utils.js
│   │   └── date-utils.js
│   └── config/
│       ├── database-config.js
│       └── app-config.js
├── tests/
├── docs/
├── package.json
└── README.md

Спеціальні файли — дотримуйтесь конвенцій

Деякі файли мають усталені імена. Не винаходьте велосипед:

README.md
LICENSE
CHANGELOG.md
CONTRIBUTING.md
package.json
.gitignore
.env

CSS та HTML: краса у простоті

CSS класи — завжди kebab-case

/* ✅ Правильно */
.user-profile {
  background: white;
}

.navigation-menu {
  display: flex;
}

/* ✅ BEM методологія */
.card { /* блок */ }
.card__header { /* елемент */ }
.card--featured { /* модифікатор */ }

/* ❌ Уникайте */
.userProfile { /* camelCase не прийнятий у CSS */ }
.user_profile { /* snake_case не прийнятий у CSS */ }

CSS змінні — організуйте систематично

:root {
  /* ✅ Логічне групування */
  --color-primary: #007bff;
  --color-secondary: #6c757d;
  --font-size-large: 1.5rem;
  --spacing-medium: 16px;
  --border-radius-small: 4px;
}

HTML атрибути — все малими літерами

<!-- ✅ Стандартно -->
<div class="user-card" data-user-id="123">
  <img src="avatar.jpg" alt="User avatar" loading="lazy">
  <button type="submit" aria-label="Submit form">Submit</button>
</div>

<!-- ❌ Проблематично -->
<div class="userCard" data-userId="123">
  <Button Type="Submit">

TypeScript: типи та інтерфейси

TypeScript додає додатковий шар іменування через типи:

// ✅ PascalCase для типів та інтерфейсів
interface UserData {
  id: number;
  firstName: string;
  lastName: string;
  isActive: boolean;
}

type ApiResponse<T> = {
  data: T;
  status: number;
  message: string;
};

// ✅ Enum теж у PascalCase
enum UserRole {
  Admin = 'admin',
  User = 'user',
  Guest = 'guest'
}

// ✅ Дженерик типи
interface Repository<T> {
  findById(id: string): Promise<T>;
  save(entity: T): Promise<T>;
}

API та Backend: RESTful угоди

Ендпоінти — дотримуйтесь REST

✅ Правильні REST ендпоінти:
GET /api/users
GET /api/users/:id
POST /api/users
PUT /api/users/:id
DELETE /api/users/:id

✅ Для складних ресурсів:
GET /api/user-profiles
GET /api/order-items
POST /api/password-reset

Query параметри — оберіть стиль і дотримуйтесь його

✅ camelCase (якщо JSON API):
GET /api/users?firstName=John&isActive=true

✅ snake_case (якщо дотримуєтесь цієї конвенції):
GET /api/users?first_name=John&is_active=true

Бази даних: snake_case править

У світі SQL snake_case — король:

-- ✅ Послідовно використовуйте snake_case
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  first_name VARCHAR(100),
  last_name VARCHAR(100),
  email VARCHAR(255) UNIQUE,
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- ✅ Зв'язуючі таблиці
CREATE TABLE user_roles (
  user_id INTEGER REFERENCES users(id),
  role_id INTEGER REFERENCES roles(id)
);

Змінні оточення та Git

.env файли — SCREAMINGSNAKECASE

# ✅ Все у верхньому регістрі
DATABASE_URL=postgresql://localhost:5432/mydb
API_BASE_URL=https://api.example.com
JWT_SECRET=your-secret-key
NODE_ENV=production
PORT=3000

Git коміти — Conventional Commits

# ✅ Використовуйте стандартні префікси
feat: add user authentication
fix: resolve login validation bug
docs: update API documentation
style: fix code formatting
refactor: simplify user service logic
test: add unit tests for user model
chore: update dependencies

Гілки — описові імена

git checkout -b feature/user-authentication
git checkout -b fix/login-validation
git checkout -b hotfix/security-patch

Інструменти для автоматизації

ESLint конфігурація для TypeScript

{
  "extends": [
    "eslint:recommended",
    "@typescript-eslint/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "rules": {
    "camelcase": ["error", { "properties": "always" }],
    "@typescript-eslint/naming-convention": [
      "error",
      {
        "selector": "variableLike",
        "format": ["camelCase"]
      },
      {
        "selector": "typeLike",
        "format": ["PascalCase"]
      }
    ]
  }
}

package.json скрипти

{
  "scripts": {
    "lint": "eslint src/",
    "format": "prettier --write src/",
    "lint:css": "stylelint src/**/*.css"
  }
}

Поширені помилки та як їх уникати

❌ Змішування стилів

// Погано — різні стилі в одному проєкті
const user_name = 'John'; // snake_case
const userAge = 25; // camelCase
const UserEmail = '[email protected]'; // PascalCase

❌ Неописові імена

// Погано
const d = new Date();
const u = getUser();
const f = () => {};

// Добре
const currentDate = new Date();
const currentUser = getUser();
const validateEmail = () => {};

❌ Угорська нотація

// Погано — не використовуйте префікси типів
const strUserName = 'John';
const intUserAge = 25;
const boolIsActive = true;

// Добре — типи зрозумілі з контексту
const userName = 'John';
const userAge = 25;
const isActive = true;

Практичні рекомендації для команди

  1. Створіть style guide для вашої команди та задокументуйте прийняті рішення
  2. Використовуйте лінтери — ESLint, Prettier, StyleLint автоматизують перевірку стилю
  3. Документуйте винятки — якщо порушуєте загальні правила, поясніть чому
  4. Code review — зверніть увагу на іменування під час рев’ю коду
  5. Поступове впровадження — не намагайтеся перейменувати все відразу, робіть це ітеративно

Висновок

Хороші угоди про іменування — це інвестиція в довгострокову підтримуваність проєкту. Вони роблять код більш читабельним, зменшують кількість помилок та прискорюють роботу команди.

Пам’ятайте: найкращі угоди — ті, яких дотримуються всі учасники проєкту. Почніть з малого, будьте послідовними та не бійтеся адаптувати правила під потреби вашої команди.

Які угоди про іменування використовуєте ви? Поділіться своїм досвідом у коментарях!

Підписуйтеся на Telegram-канал «DOU #tech», щоб не пропустити нові технічні статті

👍ПодобаєтьсяСподобалось3
До обраногоВ обраному3
LinkedIn
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter