Web-Dev-For-Beginners/translations/ru/7-bank-project/3-data/assignment.md

Задание по рефакторингу кода и документации

Цели обучения

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

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

Обзор задания

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

Инструкции

Преобразуйте текущий код app.js, применив три основных метода рефакторинга:

1. Выделение конфигурационных констант

Задача: Создайте раздел конфигурации в начале файла с переиспользуемыми константами.

Рекомендации по реализации:

• Выделите базовый URL API сервера (который сейчас жестко прописан в нескольких местах)
• Создайте константы для сообщений об ошибках, которые используются в нескольких функциях
• Рассмотрите возможность выделения путей маршрутов и идентификаторов элементов, которые часто повторяются

Пример структуры:

// Configuration constants
const API_BASE_URL = 'http://localhost:5000/api';
const ROUTES = {
  LOGIN: '/login',
  DASHBOARD: '/dashboard'
};

2. Создание единой функции запросов

Задача: Создайте переиспользуемую функцию sendRequest(), которая устранит дублирование кода между функциями createAccount() и getAccount().

Требования:

• Обработка запросов GET и POST
• Корректная обработка ошибок
• Поддержка различных URL-адресов
• Прием необязательных данных тела запроса

Рекомендации по сигнатуре функции:

async function sendRequest(endpoint, method = 'GET', data = null) {
  // Your implementation here
}

3. Добавление профессиональной документации кода

Задача: Документируйте ваш код с помощью четких и полезных комментариев, объясняющих "почему" за вашей логикой.

Стандарты документации:

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

Пример стиля документации:

/**
 * Authenticates user and redirects to dashboard
 * @param {Event} event - Form submission event
 * @returns {Promise<void>} - Resolves when login process completes
 */
async function login(event) {
  // Prevent default form submission to handle with JavaScript
  event.preventDefault();
  
  // Your implementation...
}

Критерии успеха

Ваш реорганизованный код должен демонстрировать следующие профессиональные методы разработки:

Примерная реализация

• ✅ Константы: Все "магические строки" и URL-адреса выделены в четко названные константы
• ✅ Принцип DRY: Общая логика запросов объединена в переиспользуемую функцию sendRequest()
• ✅ Документация: Функции имеют четкие комментарии JSDoc, объясняющие назначение и параметры
• ✅ Организация: Код логически сгруппирован с заголовками разделов и единообразным форматированием
• ✅ Обработка ошибок: Улучшена обработка ошибок с использованием новой функции запросов

Достаточная реализация

• ✅ Константы: Большинство повторяющихся значений выделено, хотя остаются незначительные жестко прописанные значения
• ✅ Факторизация: Создана базовая функция sendRequest(), но она может не учитывать все крайние случаи
• ✅ Комментарии: Основные функции документированы, хотя некоторые объяснения могли бы быть более полными
• ✅ Читаемость: Код в целом хорошо организован, хотя есть области для улучшения

Требуется улучшение

• ❌ Константы: Многие "магические строки" и URL-адреса остаются жестко прописанными в файле
• ❌ Дублирование: Значительное дублирование кода остается между похожими функциями
• ❌ Документация: Отсутствуют или недостаточные комментарии, которые не объясняют назначение кода
• ❌ Организация: Код не имеет четкой структуры и логической группировки

Тестирование реорганизованного кода

После реорганизации убедитесь, что ваше банковское приложение все еще работает корректно:

1. Протестируйте все пользовательские сценарии: Регистрация, вход, отображение панели управления и обработка ошибок
2. Проверьте API-запросы: Убедитесь, что ваша функция sendRequest() работает как для создания аккаунта, так и для его получения
3. Проверьте сценарии ошибок: Тестируйте с недействительными учетными данными и сетевыми ошибками
4. Проверьте вывод в консоль: Убедитесь, что при реорганизации не были введены новые ошибки

Руководство по отправке

Отправьте ваш реорганизованный файл app.js с:

• Четкими заголовками разделов, организующими различный функционал
• Единообразным форматированием и отступами кода
• Полной документацией JSDoc для всех функций
• Кратким комментарием в начале, объясняющим ваш подход к реорганизации

Бонусное задание: Создайте простой файл документации кода (CODE_STRUCTURE.md), который объясняет архитектуру вашего приложения и то, как различные функции взаимодействуют друг с другом.

Связь с реальным миром

Это задание отражает тип работы по поддержке кода, которую профессиональные разработчики выполняют регулярно. В условиях работы в индустрии:

• Код-ревью оценивают читаемость и удобство поддержки, как в этом задании
• Технический долг накапливается, если код не реорганизуется и не документируется регулярно
• Командная работа зависит от четкого, хорошо документированного кода, который могут понять новые члены команды
• Исправление ошибок становится намного проще в хорошо организованных кодовых базах с правильными абстракциями

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

---

Отказ от ответственности:
Этот документ был переведен с использованием сервиса автоматического перевода Co-op Translator. Несмотря на наши усилия обеспечить точность, автоматические переводы могут содержать ошибки или неточности. Оригинальный документ на его родном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется профессиональный перевод человеком. Мы не несем ответственности за любые недоразумения или неправильные интерпретации, возникающие в результате использования данного перевода.