10 распространённых признаков проблем в коде и как их устранить

Код-«запах» — это признак, что участок кода следует переработать: он может работать сейчас, но усложняет поддержку и развитие. В статье подробно рассмотрены 10 распространённых запахов кода, что искать, как их исправлять, критерии приёмки рефакторинга, чек‑листы для ролей и практический плейбук для безопасного улучшения кода.

О чём эта статья

Эта статья полезна разработчикам всех уровней, ревьюерам и тимлидам. Она переводит классические определения code smells на понятный русский язык, даёт практические шаги по «дезодорации» кода и содержит готовые чек‑листы и ментальные модели для принятия решений.

Содержание

• 1. Тесная связанность
• 2. «Бог-объекты»
• 3. Длинные функции
• 4. Чрезмерное количество параметров
• 5. Плохо выбранные идентификаторы
• 6. Магические числа
• 7. Глубокая вложенность
• 8. Необработанные исключения
• 9. Дублирование кода
• 10. Отсутствие комментариев
• Как писать «беззапаховый» код: стратегии и проверочный список
• Ментальные модели и когда не рефакторить
• Плейбук рефакторинга: пошагово
• Чек‑листы по ролям
• Диаграмма принятия решения (Mermaid)
• Краткое резюме
• Глоссарий — одно предложение на термин

Введение: что такое “запах кода” в одном предложении

Запах кода — это симптом потенциальной архитектурной или проектной проблемы: участок кода, который удобнее и безопаснее улучшить сейчас, чтобы избежать больших затрат впоследствии.

Важно: запах кода не равен багу. Это предупреждение о повышенном риске технического долга.

1. Тесная связанность

Проблема

Тесная связанность (tight coupling) возникает, когда два класса или модуля завязаны друг на друга так сильно, что изменение одного требует изменений во втором. Это замедляет развитие и увеличивает риск регрессий.

Пример

class Worker {
  Bike bike = new Bike();
  public void commute() {
    bike.drive();
  }
}

Здесь класс Worker зависит от конкретной реализации Bike. Если захотите использовать Car — придётся менять Worker.

Решение

Добавьте уровень абстракции: выделите интерфейс Vehicle и внедряйте зависимость через поле/конструктор/сеттер.

class Worker {
  Vehicle vehicle;
  public void changeVehicle(Vehicle v) {
    vehicle = v;
  }
  public void commute() {
    vehicle.drive();
  }
}

interface Vehicle {
  void drive();
}

class Bike implements Vehicle {
  public void drive() {
  }
}

class Car implements Vehicle {
  public void drive() {
  }
}

Когда этот подход не нужен

• Тесная связь допустима для маленьких утилитных скриптов с коротким сроком жизни.
• Если код действительно никогда не должен меняться и проект одноразовый.

Критерии приёмки

• Компоненты тестируются отдельно с моками/стабами.
• Добавление новой реализации Vehicle не требует изменения Worker.

2. «Бог-объекты» (God Objects)

Проблема

Бог-объект — это класс, который «знает слишком много» и «делает слишком много»: содержит переменные и методы, относящиеся к разным аспектам доменной логики. Это приводит к высокой связанности и катастрофическому росту сложности.

Подход к решению

1. Выделите разные ответственности в отдельные сущности (например, Credentials, Profile).
2. Применяйте композицию вместо монолита.
3. Проверьте зависимости и уменьшите публичное API класса.

Пример трансформации

Исходный монстр:

class User {
  public String username;
  public String password;
  public String address;
  public String zipcode;
  public int age;
  ...
  public String getUsername() {
    return username;
  }
  public void setUsername(String u) {
    username = u;
  }
}

Сплит по ролям:

class User {
  Credentials credentials;
  Profile profile;
  ...
}

class Credentials {
  public String username;
  public String password;
  ...
  public String getUsername() {
    return username;
  }
  public void setUsername(String u) {
    username = u;
  }
}

Ментальные модели

• Single Responsibility Principle (SRP): каждая сущность должна иметь одну причину для изменения.
• «Разделяй и властвуй»: разделение обязанностей облегчает тестирование и поиск ошибок.

Ошибки при рефакторинге

• Вырезание классов без изменения публичного API приведёт к увеличению проксирующих методов и не уменьшит сложность.
• Слишком тонкое дробление создаёт огромное количество мелких классов без смысла.

3. Длинные функции

Проблема

Функция, растущая «до небес», обычно решает слишком много задач и сложна для понимания и тестирования.

Правило великого программиста

Если функция не помещается на экран без скролла (или вы теряете фокус при чтении), скорее всего, она слишком длинна.

Решение

• Разделяйте алгоритм на подзадачи.
• Каждая новая функция должна решать одну понятную задачу и иметь понятное имя.
• Оригинальная функция превращается в orchestration-контроллер, который вызывает подфункции в правильном порядке.

Пример подхода

Разбейте процесс валидации, подготовки данных и отправки в разные методы: validate(), prepare(), send().

4. Чрезмерное количество параметров

Проблема

Функция или конструктор с большим числом параметров сложна для понимания и тестирования; это часто сигнализирует о нечеткой ответственности.

Практическое правило

Будьте осторожны после 3 параметров. Если их больше — подумайте об упаковке значений в объект (parameter object) или о разделении функции.

Паттерны решения

• Parameter Object: соберите связанный набор параметров в отдельный класс.
• Builder: для конструктора с множеством опциональных параметров используйте шаблон Builder.
• Разделение ответственности: возможно, функция пытается делать несколько вещей.

5. Плохо выбранные идентификаторы

Проблема

Краткие, непонятные или неунифицированные имена переменных, функций и классов портят читаемость. Это увеличивает время погружения в код и риск ошибок.

Практика хорошего именования

• Переменные: короткие, но осмысленные (userName, totalCount).
• Функции: в имени должен быть глагол (calculateTax, fetchUsers).
• Классы: существительные, отражающие роль (OrderService, UserRepository).
• Следуйте стилевому гайду команды и используйте автоформатters/линтеры.

Когда не стоит переименовывать

• В тестах, где имя хранит семантику сценария (можно, но осторожно).
• В условиях с жёсткой обратной совместимостью API — обсуждайте и документируйте изменения.

6. Магические числа

Проблема

Магические числа — это «жестко захардкоженные» числовые литералы в коде, смысл которых непонятен без контекста.

Решение

• Заменяйте магические числа именованными константами или перечислениями (enum).
• Константы помогают понять назначение и упростить изменение значения в одном месте.

Пример

Плохо:

if (status == 3) { ... }

Лучше:

public static final int STATUS_CLOSED = 3;
if (status == STATUS_CLOSED) { ... }

7. Глубокая вложенность

Проблема

Слишком много вложенных циклов и условий ухудшает читаемость и делает код хрупким.

Подходы к упрощению

• Ранние возвраты (early return) уменьшают уровни вложенности.
• Вынесите вложенные блоки в отдельные функции с понятными именами.
• Используйте функции высшего порядка или stream/collection-API вместо ручных вложенных циклов, где это уместно.
• Для сложной логики рассмотрите шаблоны State Machine или Strategy.

Контрпример

Иногда вложенность отражает реальную многомерную природу данных (например, разбор дерева). В таких случаях лучше концентрироваться на читабельности через именованные вспомогательные функции.

8. Необработанные исключения

Проблема

Игнорирование исключений (пустые catch-блоки) или перехват слишком общих исключений делает отладку сложной и скрывает реальные ошибки.

Рекомендации

• Ловите конкретные исключения, а не Exception или Throwable.
• Логируйте стек-трейс и контекст.
• Реагируйте адекватно: повтор, откат транзакции, пользователю — понятное сообщение.
• Если исключение не может обработать текущий уровень, пробросьте его вверх, оформляя собственные типы исключений при необходимости.

9. Дублирование кода

Проблема

Копипаст в нескольких местах затрудняет изменение поведения: забыли обновить в одном месте — получили баг.

Решение

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

Пример

Плохой фрагмент:

String queryUsername = getSomeUsername();
boolean isUserOnline = false;

for (String username : onlineUsers) {
  if (username.equals(queryUsername)) {
    isUserOnline = true;
  }
}

if (isUserOnline) {
  ...
}

Лучше:

public boolean isUserOnline(String queryUsername) {
  for (String username : onlineUsers) {
    if (username.equals(queryUsername)) {
      return true;
    }
  }
  return false;
}

10. Отсутствие комментариев

Проблема

Полное отсутствие комментариев и документации усложняет понимание нефункциональных требований, причин бизнес-решений и ожидаемых побочных эффектов.

Правило полезных комментариев

• Комментируйте «почему», а не «что». Код уже показывает что — комментарий объясняет мотивацию.
• Пишите краткие заголовки для модулей и описания публичного API.
• Поддерживайте документацию рядом с кодом (docblocks, README для сложных модулей).

Как писать код, который не «пахнет»

Ключевые принципы:

• DRY (Don’t Repeat Yourself): избегайте дублирования.
• SRP (Single Responsibility Principle): одна ответственность = одна причина для изменения.
• KISS (Keep It Simple, Stupid): проще — лучше.
• YAGNI (You Aren’t Gonna Need It): не усложняйте заранее.

Частые практики улучшения качества:

• Код‑ревью с чек‑листом запахов.
• Автоматические линтеры и статический анализ.
• Наличие модульных и интеграционных тестов.
• Непрерывная интеграция, где выполнение тестов — обязательный шаг.

Ментальные модели и эвристики

1. «Маленькие изменения, частые релизы» — легче откатить и проще поддерживать.
2. «Закон двух изменений»: если вы меняете в двух местах одновременно, подумайте, можно ли сделать это в одном месте.
3. «Принцип минимальной боли»: начните с наиболее рискованного/болезненного запаха.
4. «Рефакторить к тестам»: добавьте тесты до рефакторинга, чтобы застраховать поведение.

Плейбук рефакторинга — пошагово

1. Определите запах: локализуйте участок кода.
2. Напишите тесты охватывающие текущее поведение.
3. Сделайте маленькие, инкрементные изменения.
4. Запустите тесты, убедитесь в отсутствии регрессий.
5. Рефакторинг: вынос в функции/классы, переименование, внедрение зависимостей.
6. Документируйте причину и результат в комментариях/коммите.
7. PR-реквизиты: опишите мотивацию и риски, добавьте чек‑лист.

Важно: избегайте больших рефакторингов без тестовой защиты.

Чек‑листы по ролям

Для разработчика

• Есть модульные тесты для текущей функциональности.
• Изменения по одному маленькому шагу.
• Поясняющий комментарий в PR по сути рефакторинга.
• Не добавлены лишние изменения формата или стиля.

Для ревьюера

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

Для тимлида

• Рефакторинг согласован с roadmap (не ломает релизные сроки).
• Ресурсы на тестирование и мониторинг есть.
• План отката и коммуникация подготовлены.

Примеры тест-кейсов и критерии приёмки

• Unit: после рефакторинга все существующие unit-тесты проходят.
• Integration: интеграционные сценарии, особенно граничные, работают как раньше.
• Performance: если был риск ухудшения производительности — добавьте бенчмарки.
• Behavioural: логика бизнес-процессов не изменилась (черный‑box тесты).

Критерии приёмки для простого рефакторинга:

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

Диаграмма принятия решения (Mermaid)

flowchart TD
  A[Нашли потенциальный 'запах' кода?] --> B{Это баг или архитектурный запах?}
  B -- Баг --> C[Починить баг и написать тест]
  B -- Запах --> D{Есть тесты на это поведение?}
  D -- Нет --> E[Написать тест'ы']
  D -- Да --> F{Рефакторить маленькими шагами?}
  F -- Да --> G[Рефакторинг + запустить тесты]
  F -- Нет --> H[Планировать поэтапный рефакторинг]
  G --> I[PR, ревью, merge]
  H --> I
  C --> I

Контрпримеры — когда не стоит рефакторить

• В срочных исправлениях на продакшне (hotfix) лучше быстро исправить баг и отложить рефакторинг на ветку.
• Если функциональность на грани вымирания и потребуется от неё отказаться — инвестиции в рефакторинг не окупятся.
• В очень старых проектах, где refactor << rewrite: иногда быстрее переписать модуль, чем поддерживать его.

Безопасность и приватность при рефакторинге

• Не перемещайте чувствительные данные в лог без маскирования.
• При изменении мест хранения данных проверьте соответствие GDPR/локальным законам о защите данных.
• Обновляйте миграции данных с тестовыми сценариями и бэкапом.

Краткое резюме

• Запахи кода — сигналы к улучшению, но они не равны багам.
• Рефакторьте постепенно, сопровождая тестами и документируя мотивацию.
• Используйте чек‑листы и роли для безопасного процесса.
• Иногда лучше не рефакторить: срочные исправления и устаревшие функции — исключения.

Однострочный глоссарий

• Code smell — признак потенциальной проблемы в дизайне кода.
• SRP — принцип единой ответственности.
• DRY — не повторяй себя.
• Early return — ранний выход из функции для уменьшения вложенности.

Что вам показалось самым полезным в статье? Поделитесь своим опытом в комментариях: какие запахи кода вы встречаете чаще всего и как с ними боретесь.

Image Credit: SIphotography/ Depositphotos