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

Повний гайд з угод про імена у веб-розробці
Чому іменування — це не просто дрібниці
Уявіть, що ви відкриваєте чужий код і бачите змінну 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;
Практичні рекомендації для команди
- Створіть style guide для вашої команди та задокументуйте прийняті рішення
- Використовуйте лінтери — ESLint, Prettier, StyleLint автоматизують перевірку стилю
- Документуйте винятки — якщо порушуєте загальні правила, поясніть чому
- Code review — зверніть увагу на іменування під час рев’ю коду
- Поступове впровадження — не намагайтеся перейменувати все відразу, робіть це ітеративно
Висновок
Хороші угоди про іменування — це інвестиція в довгострокову підтримуваність проєкту. Вони роблять код більш читабельним, зменшують кількість помилок та прискорюють роботу команди.
Пам’ятайте: найкращі угоди — ті, яких дотримуються всі учасники проєкту. Почніть з малого, будьте послідовними та не бійтеся адаптувати правила під потреби вашої команди.
Які угоди про іменування використовуєте ви? Поділіться своїм досвідом у коментарях!
Немає коментарів
Додати коментар Підписатись на коментаріВідписатись від коментарів