Как перевести код из состояния «работает» в полноценную готовую работу.

Наконец, вы закончили свою задачу и уже нажали кнопку запроса на вытягивание… Стоп!

Найдите минутку, чтобы обдумать следующие вопросы. Эти рекомендации помогут сделать ваш код более читабельным и предсказуемым.

Приведенные здесь примеры написаны на Java, но не беспокойтесь, следующие советы можно реализовать в любом стеке.

Пункты для проверки после того, как код сделан.

Добавляем ли мы business logs, чтобы указать, что операция запущена и завершена без ошибок?

У нас должно быть «Сообщение об успехе», которое мы можем быстро определить при изучении проблемы пользователя.

OP-INFO. Registraion request. Registering a user with email: [email protected].
...other log messages...
OP-INFO. Registraion request. Successfuly registered a user with email: [email protected].

Здесь мы также использовали пользовательский префикс OP-INFO (информация об операции), чтобы иметь возможность в будущем выбирать такие бизнес-сообщения из беспорядка журналов отладки.

Мы log a raw request получили и отправили ответ?
*только для конечных точек интеграции и веб-перехватчиков

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

Do we handle errors ?

Нужно обернуть сервисный метод блоком try-catch и подумать, что там может пойти не так и как действовать в таких случаях.

Сначала попытайтесь найти определенные исключения, которые вы можете перехватить и обработать, а затем поместить общий перехват в конец.

try {   
  tryRegister(...) 
} catch (...) { 
} catch (...) { 
}

Должны ли мы use mappers создавать DTO?

Мы должны избегать создания объектов DTO на месте. В будущем может быть несколько способов (источников) для создания одного и того же DTO, поэтому все сопоставления должны быть расположены в одном месте.

Обрати внимание на

Избегайте кода в блоке try

❌ Плохо — Много всего в одном месте…

✅ Хорошо. Сосредоточьтесь только на обработке ошибок

Избегайте кода в цикле for

Этот похож на предыдущий, но в контексте написания циклов.

❌ Плохо. Обработка логики внутри цикла — слишком много обязанностей в одном месте.

✅ Хорошо. Код обработки перемещен в отдельный метод или зависимость. Обязанности теперь четко определены.

Отсутствует сообщение технического журнала в месте, где возникает исключение

❌ Плохо. Легко забыть добавить блок catch для этого конкретного исключения, поэтому реальная причина ошибки может быть упущена или неясна.

✅ Хорошо. Теперь мы предоставили техническое сообщение журнала (для разработчиков) в том месте, где выдается ошибка.
Кроме того, мы перехватываем ее на более высоком уровне с помощью сообщения бизнес-журнала, которое сформулировано более дружелюбно для нетехнических коллег.

Это будет особенно полезно, если вам лень создавать определенные исключения и вместо этого использовать общий RuntimeException() для всех ситуаций.

Я настоятельно рекомендую приобрести расширение, такое как GitHub Copilot, которое может писать для вас описательные тексты ошибок.

Всегда обрабатывайте известные ошибки в первую очередь.

❌ Плохо. Единый обработчик всех возможных ошибок. Это затрудняет выявление причины проблемы и предоставление рекомендаций по ее решению.

✅ Хорошо. Мы обрабатываем ожидаемую ошибку, поэтому можем написать полезное сообщение, указывающее на проблему.
Кроме того, мы сообщаем, что общая ошибка является для нас неожиданной, чтобы привлечь дополнительное внимание.

Избегайте создания DTO на месте

❌ Плохо. Когда мы добавим в класс новые поля, не будет единого места для исправления сопоставления.

  • Мы должны искать и вносить правки во всех задействованных местах.
  • Одно добавленное поле может привести к изменению нескольких файлов;
  • Это раздувает код.

✅ Хорошо.

  • Выглядит компактно.
  • Легко добавлять новые сопоставления в одном месте — нет необходимости проходить всю бизнес-логику только для настройки нового поля.

Я уверен, что эти простые советы помогут вам вывести свой код на новый уровень, улучшить его читабельность и поддержку проекта в будущем.

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