Clean Code

Практичные стандарты программирования для написания чистого и поддерживаемого кода — именование, функции, структура, антипаттерны и проверки перед изменениями. Используйте при написании нового кода, рефакторинге, ревью качества или внедрении стандартов разработки.

Основные принципы

• SRP (Принцип единственной ответственности) — каждая функция или класс делает ОДНУ вещь.
  Проверка: можно ли описать это без слова «и»?
• DRY — не повторяйся.
  Проверка: писал ли я это раньше?
• KISS — делай максимально просто.
  Проверка: есть ли более простой способ?
• YAGNI — не делай лишнего.
  Проверка: это действительно нужно сейчас?
• Boy Scout Rule — оставляй код чище, чем нашёл.
  Проверка: стал ли файл лучше после изменений?

Правила именования

Имена — это главная документация. Хорошее имя устраняет необходимость комментариев.

• Переменные — должны отражать смысл: userCount, elapsed
• Функции — глагол + сущность: getUserById()
• Булевы значения — в форме вопроса: isActive, hasPermission
• Константы — SCREAMING_SNAKE_CASE
• Классы — существительные: UserRepository

Если имя требует комментария — переименуйте его.

Антипаттерны именования

• Сокращения (usrMgr) — становятся непонятными со временем
• Общие слова (data, info) — не несут смысла
• Вводящие в заблуждение имена — не соответствуют поведению
• Венгерская нотация — избыточна при наличии типов

Правила функций

• Короткие (до 20 строк, лучше 5–10)
• Делают одну вещь
• Один уровень абстракции
• Минимум аргументов (0–3)
• Без неожиданных побочных эффектов

Guard Clauses

Избегайте глубокой вложенности, используйте ранние возвраты.

// Плохо
if (order) {
 if (order.items.length > 0) {
 ...
 }
}

// Хорошо
if (!order) throw new Error();
if (!order.items.length) throw new Error();

Объекты параметров

Если аргументов больше трёх — используйте объект.

// Плохо
createUser('John', 'Doe', ...);

// Хорошо
createUser({ firstName: 'John', lastName: 'Doe' });

Структура кода

• Предпочитайте плоскую структуру вместо вложенной
• Разбивайте сложную логику на композиции
• Держите связанный код рядом
• Выделяйте функции вместо комментариев

Композиция вместо «божественных функций»

// Плохо
function processOrder() {
 // всё сразу
}

// Хорошо
function processOrder() {
 validateOrder();
 processPayment();
 updateInventory();
}

Согласованность возвращаемых значений

Функции должны возвращать предсказуемые типы. Используйте единый формат результатов.

Антипаттерны

• Комментарии к каждой строке
• Лишние абстракции
• Файлы «utils» без структуры
• Глубокая вложенность
• Магические числа
• Копипаст
• Callback hell

Проверка перед изменениями

• Кто использует этот файл?
• Что он импортирует?
• Какие тесты его покрывают?
• Это общий компонент?

Изменяйте файл вместе со всеми зависимостями в одной задаче.

Самопроверка

• Задача выполнена полностью?
• Изменены все связанные файлы?
• Код работает?
• Нет ошибок линтера?

Никогда не делайте

• Не пишите очевидные комментарии
• Не создавайте абстракции без необходимости
• Не оставляйте закомментированный код
• Не пишите длинные функции
• Не делайте глубокую вложенность
• Не используйте магические значения
• Не меняйте код без анализа зависимостей
• Не оставляйте ошибки после изменений