11 KiB

Raw Blame History Unescape Escape

Преработка на код и задача за документация

Цели на обучението

С изпълнението на тази задача ще практикувате основни умения за разработка на софтуер, които професионалните разработчици използват ежедневно. Ще се научите да организирате кода за по-добра поддръжка, да намалявате дублирането чрез абстракция и да документирате работата си за бъдещи разработчици (включително и за себе си!).

Чистият и добре документиран код е от съществено значение за реални уеб разработващи проекти, където множество разработчици работят заедно и кодовите бази се развиват с времето.

Преглед на задачата

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

Инструкции

Трансформирайте текущия си код в app.js, като приложите тези три основни техники за преработка:

1. Извличане на конфигурационни константи

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

Насоки за изпълнение:

Извлечете базовия URL на сървърния API (в момента твърдо кодиран на няколко места)
Създайте константи за съобщения за грешки, които се появяват в няколко функции
Помислете за извличане на пътища на маршрути и ID на елементи, които се използват многократно

Примерна структура:

// 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 адреси остават твърдо кодирани в целия файл
❌ Дублиране: Значително дублиране на код остава между подобни функции
❌ Документация: Липсващи или недостатъчни коментари, които не обясняват целта на кода
❌ Организация: Кодът няма ясна структура и логическо групиране

Тестване на преработения код

След преработката, уверете се, че вашето банково приложение все още функционира правилно:

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

Насоки за подаване

Подайте вашия преработен файл app.js с:

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

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

Връзка с реалния свят

Тази задача отразява типа поддръжка на код, която професионалните разработчици извършват редовно. В индустриални условия:

Прегледите на код оценяват четимостта и поддръжката, както в тази задача
Технически дълг се натрупва, когато кодът не се преработва и документира редовно
Сътрудничеството в екип зависи от ясен, добре документиран код, който новите членове на екипа могат да разберат
Поправките на грешки са много по-лесни в добре организирани кодови бази с подходящи абстракции

Уменията, които практикувате тук - извличане на константи, елиминиране на дублирането и писане на ясна документация - са основни за професионалната разработка на софтуер.

Отказ от отговорност:
Този документ е преведен с помощта на AI услуга за превод Co-op Translator. Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи може да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да било недоразумения или погрешни интерпретации, произтичащи от използването на този превод.

11 KiB Raw Blame History Unescape Escape