Definition of Done для фронтенд задач

Ви отримали завдання. Ви знаєте, як його реалізувати та з чого почати, але коли можна сказати, що завдання виконано?

Зазвичай у фронтенді відповідь на це питання залежить від команди та конкретного завдання. Для себе я створила список питань та рекомендацій для кожної позитивної відповіді. У цій статті я хочу поділитися з вами цим списком.

Photo by Glenn Carstens-Peters on Unsplash

Чи є верстка, або потрібно змінити відображення?

Потрібно внести зміни до HTML (або JSX) та/або CSS сторінки, компонента, модуля.

• [точність] Верстка повинна відповідати дизайну — кольори, шрифти, вертикальний та горизонтальний ритми, зображення — все повинно виглядати відповідно.
• [адаптивність] Не важливо, чи використовується підхід mobile-first чи desktop-first — потрібно протестувати верстку на різних розмірах екрану і вона не повинна ламатися.
• [семантика] HTML повинен бути семантично вірним, це означає, що потрібно використовувати кнопку, якщо передбачається якась дія, а посилання, якщо потрібен перехід між сторінками і т.д.
• [динаміка] Потрібно стилізувати наведення на елементи, підсвітити фокус або інші активні стани, встановити кілька шрифтів за замовчуванням, щоб зробити дизайн живим та інтуїтивним.

Чи потрібно працювати з текстом?

Вам потрібно підтримувати більше однієї мови. Є специфічні елементи для локалізації. Або просто — у задачі є текст, який потрібно додати.

• [переклад] Текст повинен бути перекладений; якщо ви підтримуєте мови, які пишуться справа наліво (наприклад, іврит або арабська) і зліва направо (наприклад, англійська або українська), вам потрібно перевірити верстку для обох варіантів.
• [форматування] Вам потрібно відформатувати дані, які незрозумілі в чистому вигляді, наприклад, дати (1582644492199, UTC “Tue, 25 Feb 2020 15:28:12 GMT”) або великі числа (2500100000).
• [локаль] Специфічні для локалізації дані повинні бути очевидними для кожного користувача, наприклад, валюта (15 це $ або UAH?), вага (50 це кг або фунти?), дроби (повинно бути 2.5 або 2,5?).
• [множина] Потрібно використовувати локалізацію для множинних чисел. Наприклад, “2 день” звучить дивно.
• [правопис] Вам необхідно перевірити текст на наявність помилок.

Чи є процес, який може займати багато часу?

Необхідно взаємодіяти з API. Потрібно завантажити важкі ресурси — скрипти, стилі або зображення. Будь-який інший процес, який займає час і може заблокувати інтерфейс користувача.

• [лодер] Вам потрібно показати, що завантаження або обчислення в процесі, щоб користувач розумів, що відбувається. Зазвичай, лодер це хороше рішення для такої задачі.
• [плейсхолдер] Якщо ви хочете зменшити перебудови контенту, замість лодера, ви можете використовувати плейсхолдер, наприклад для зображень або компонентів-карток.
• [відправка-даних] Коли вам потрібно зберегти дані, вам потрібно це показати і заблокувати всі елементи, які можуть порушити цей процес. Наприклад, показати лодер і заблокувати кнопку збереження. Після збереження, розблокувати кнопку та приховати лодер.

Чи потрібно завантажувати ресурси?

У вас є зображення, шрифти, стилі, скрипти або зовнішні сервіси.

• [зображення] Вам потрібно стиснути зображення: JPG, PNG, SVG, або ви можете використовувати npm пакети для автоматизації цього процесу. Враховуйте різні роздільні здатності екранів та використовуйте відповідні розміри для зображень.
• [шрифти] Вам потрібно вибрати стратегію завантаження шрифтів, мінімізувати файли та завантажувати лише необхідні сімейства шрифтів.
• [скрипти/стилі] Видаліть зайвий код —приберіть невикористовувані модулі та коментарі в збірці для продакшену, діліть великі файли, мініфікуйте, розділяйте та завантажуйте лише потрібний код, наприклад, файли, які використовуються на десктопі або файли, необхідні тільки для мобільної версії.
• [оптимізація] Використовуйте відкладене завантаження, prefetch/preload, defer/async для завантаження ресурсів. Але будьте уважні, завжди перевіряйте, чи допомагає вам оптимізація, і не робіть цього, якщо у вас немає ніяких проблем.

Чи потрібно працювати з користувацькими даними?

У вас є форма або окреме поле введення, з яким користувач повинен взаємодіяти, наприклад, календар, текстове поле або завантажувач файлів.

• [валідація] Вам потрібно валідувати ті дані, які ввів користувач, перш ніж відправити їх на бекенд. Якщо дані невірні, потрібно показати помилку та підсвітити поле, в якому вона з’явилась.
• [маска] Краще додавати маску введення на ті поля, в яких дані повинні бути в певному форматі, наприклад, номер телефону, електронна пошта.

Чи потрібно реалізовувати інтеграцію з бекендом?

Ви працюєте з будь-яким типом API, це може бути ваш бекенд або сторонні сервіси, наприклад, аналітика або підключення реклами.

• [помилки] Ви завжди повинні показувати, якщо щось пішло не так. Будь-який сервіс може відповісти помилкою, а користувач повинен знати результат своїх дій та причину помилки.
• [валідація] Краще показувати та підсвічувати помилки бекенд валідації так само, як ви це робите на фронтенді.
• [заглушки] Якщо результат вашого запиту повинен бути відображений, але сервер відповів помилкою, іноді краще показати заглушку замість того, щоб ховати все. Наприклад, на сторінці пошуку краще показати повідомлення “Сталася помилка, спробуйте повторити запит пізніше”, замість того, щоб залишати порожню сторінку та показувати спливаюче повідомлення про помилку.
• [деталі] Зрозумілий текст помилки допоможе вам вирішити проблему, тому старайтеся якомога рідше використовувати помилки типу “Щось пішло не так”.
• [запити] Спробуйте скоротити кількість запитів. Іноді краще домовитися з бекенд-командою та змінити API, ніж надсилати пакет запитів. Не надсилайте зайві дані та спробуйте зменшити розмір запитів.

Чи є у вас дані, які ви не хочете втратити після перезавантаження сторінки?

У вас є сторінки, вкладки, модальні вікна, важливі форми, таймери, будь-які види блокувальників, наприклад, блокування кнопки “Надіслати SMS”.

• [стан] Найкраще використовувати URL, щоб зберегти стан сторінки для користувача, тоді після перезавантаження сторінки користувач отримає потрібну сторінку, відкрите модальне вікно або останню відкриту вкладку. Ви можете зберігати такі дані в localStorage, sessionStorage або в URL (query параметри або хеш).
• [дані] Вам потрібно зберігати важливі дані — токен авторизації або велику важливу форму, яку користувач почав заповнювати. Ви можете зберігати такі дані в localStorage, sessionStorage, Cookies, IndexedDB. Але будьте обережні з конфіденційними даними — завжди пам’ятайте про безпеку ваших користувачів.
• [блокувальники] Вам потрібно зберігати дані, які допомагають блокувати UI, щоб користувач не міг зламати ваш додаток, наприклад, не міг надсилати собі валідаційне SMS занадто часто, або не міг писати коментарі, якщо щойно був заблокований. Завжди пам’ятайте про безпеку вашого додатка. Краще використовувати URL для таких даних, тоді у користувача менше шансів зламати вашу блокувальну функцію, якщо спробує перейти в інший браузер.

Чи потрібно працювати з великим обсягом даних?

У вас є списки, таблиці або будь-які інші послідовності даних.

• [пагінація] Якщо вам потрібно показати багато інформації, краще використовувати пагінацію або безкінечну прокрутку.
• [фільтрація] Гарною практикою є додавання фільтрації та сортування для роботи з великою кількістю даних.

Чи є у вас сторінки або стани сторінки, якими користувач може захотіти поділитися?

У вас є сторінка пошуку, пагінація або фільтрація, сторінки CRUD для будь-якої сутності або будь-який інший стан додатка, яким користувач захоче поділитися.

• [маршрутизація] Вам потрібно створити зручну маршрутизацію. Гарною практикою буде використовувати для цього RESTful API угоду.
• [стан] Краще зберігати стан додатка в URL, наприклад, search=abc, page=4, #loginModal. При такій реалізації користувачі можуть ділитися станом додатка, а не тільки сторінками.

Ваша команда пише тести?

• [unit] Якщо у вас є нестандартна логіка, то краще покрити її юніт-тестами.
• [snapshot] Якщо у вас є динамічний UI, краще такі місця покрити снепшот або скріншот-тестами (які більш складні та менш стійкі до відмов). Наприклад, у вашій формі набір полів відрізняється для кожного користувача.
• [e2e] Найкраще основний функціонал покривати E2E-тестами, наприклад, CRUD головних сутностей.

Ваша команда пише документацію?

Чудово, коли у нас є код, який пояснюється сам собою, але на практиці цього не завжди достатньо.

• [UI] Для компонентів найкраще використовувати сервіси storybook або styleguidist.
• [сутності] Документація сутності/сторінки може складатися з посилань на дизайн, документацію API, юзер сторі, які стосуються задачі. А також опис складної логіки, неочевидних рішень, нестандартної поведінки. Приклади: “Сторінка входу”, “Віджет налаштувань”.
• [неочевидності] Деякі рішення, які ви приймаєте під час розробки, можуть бути неочевидними, такі рішення найкраще пояснити окремо. Наприклад: “Локалізація в додатку”, “Графік зарплат — як це працює”.
• [how-to] Найкорисніша документація відповідає на ваші запитання. Тому задокументувати відповіді на основні запитання — це відмінний вибір. Наприклад: “Як створити реліз?”, “Як тестувати додаток?”, “Як ми робимо API запити?”
• [інфраструктура] Документація про структуру вашого проекту, вашої команди та вашого робочого процесу — це відмінна стартова документація для нових розробників. Така документація може містити корисні посилання, схеми, чек-листи. Приклади: “Репозиторії”, “Стратегія гілок та найменування”, “Новим розробникам”.

Висновки

Цей список не є обов’язковим і навіть не на 100% повним, оскільки тільки ви можете вирішувати, що найкраще для вашої команди або вашого проекту. Але сподіваюся, що ця стаття стане хорошою стартовою точкою для вашого особистого “definition of done”.

Ймовірно, я щось пропустила, тому якщо у вас є що додати, будь ласка, напишіть це у коментарі.

Дякую за те, що дочитали!
Побачимось наступного разу! 🤹🏻‍♀️

This story in English:

Definition of Done for front-end tasks