Як дати конструктивний код перегляду зворотного зв'язку

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

Для людей, для яких англійська не є рідною мовою, коментарі до перегляду коду представляють особливий виклик: як ви можете бути прямими щодо проблем, не звучачи жорстко, і ввічливими, не будучи нечіткими? Цей підручник надає вам мову для виконання обох операцій.

---

Принципи хорошої мови перегляду коду

Перед фразами, зрозумійте цілі:

• ** Будь конкретним ** — скажи точно, що це за проблема і де
• ** Поясніть чому ** — допоможіть автору зрозуміти аргументацію, а не лише висновок
• ** Використовувати питання ** — питання здаються співпрацею; речення здаються командами
• ** Позначте ваш намір ** — повідомляє, чи є коментар блокуванням, пропозицією або питанням
• ** Підтверджувати хорошу роботу ** — позитивні коментарі будують довіру і підсилюють хороші звички

---

Позначте свої коментарі

Одним з найефективніших способів професійного перегляду коду є додавання до коментарів мітки, яка свідчить про намір автора:

• ** Блокер: ** або ** Потрібно виправити: ** — цей параметр слід змінити перед об’ єднанням
• ** Suggestion: ** або ** Nit: ** — невелике поліпшення, яке було б гарним, але не обов’ язковим
• ** Питання: ** — Я не розумію цього і потребую пояснення
• ** Похвала: ** — це хороша робота, яка заслуговує уваги

• “Blocker: Ця функція не обробляє регістр, якщо вхідний параметр є нульовим. Він буде скинути на час виконання.»*

“Nit: Незначні відмінності у стилі — я витягну це до названої константи, а не використовую магічне число безпосередньо.”

• ”** Питання: ** Що станеться, якщо цей виклик API перевищить час очікування? Я не бачу тут обробника тайм-аутів».*

• ”** Похвала:** Гарний підхід до логіки кешування — це набагато чистіше, ніж попередня реалізація.” *

---

Фрази для ідентифікації проблем

Виступав за «Буковину»

• “Я думаю, що тут може бути помилка — якщо user не визначено, цей рядок поверне TypeError.” *

“Це я перевернув. Чи має це бути >=, а не <=?”

• “Я помітив, що ця функція змінює вхідний масив безпосередньо. Это было намеренно? Це може викликати несподівані побічні ефекти для викликаючих.»*

Підвищення продуктивності

• “Це виклик бази даних у циклі, що призведе до N+1 запитів. Ми могли б зробити це з одним запитом.”*

• “Залежно від розміру вхідного файла, це може призвести до зниження швидкодії. Чи ми порівняли це з великими наборами даних?»*

Флагманські проблеми безпеки

“Це схоже на потенційну вразливість втручання SQL — нам слід використовувати параметризовані запити.”

• “Не слід записувати в журнал конфіденційні дані. Чи можемо ми замаскувати або виключити це поле в повідомленні журналу?»*

---

Фрази для внесення пропозицій

Представлені альтернативні варіанти

• “Чи ви розглядали можливість використання [підходу]? Це може бути простіше і легше перевірити.»*

“Одним з варіантів було б виділити це у окрему функцію — це зробило б логіку тут простішою для розуміння.”

“Ми маємо функцію утиліти для цього в utils/string.ts — може бути варто використовувати її знову, а не реалізовувати знову.”

Рекомендуємо спрощення

“Це можна було б спростити до однією рядком за допомогою Array.prototype.find.”

• “Умовна логіка тут досить складна. Таблиця пошуку може зробити це більш читабельним.”*

---

Фрази для запитання

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

*“Чи можете ви допомогти мені зрозуміти, що стоїть за цим підходом? Я хочу переконатися, що я нічого не пропускаю»

• “Що робить цей прапорець? Назва не відразу зрозуміла для мене — чи можемо ми перейменувати її або додати коментар?»*

• “Чи є тест для цього краю? Мені цікаво, що станеться, коли список буде порожній.»*

---

Фрази для визнання хорошої роботи

Не недооценюй цінність позитивних коментарів. Вони мотивують авторів і підсилюють хороші моделі.

“Дійсно чисте рішення — я не думав про такий підхід.”

• “Обробка помилок тут відмінна. Добре оборонне кодування.”*

• “Ця рефакторизація робить намір набагато яснішим. Добре зроблено

---

Фрази для відповіді на коментарі перегляду

Якщо ви є автором, який отримує зворотній зв’ язок, важливо, як ви відповідаєте на нього.

Визнаючи і приймаючи

• “Хороший випадок — я оновив це в останньому занесенні.” *

*“Ти маєш рацію, я пропустив цей крайній випадок. Зараз ліквідований»

Пояснює свої мотиви

“Я вибрав цей підхід, тому що [причина]. Чи має це сенс, чи ви все ще віддасте перевагу [альтернативі]?»

З повагою не погоджуюсь

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

« Я б хотів залишити це на даний момент — чи не могли б ми створити окремий квиток, щоб переглянути це, якщо це стане проблемою? »

---

Мова перегляду коду формує командну культуру. Інженери, які переглядають код з емпатією, точністю і ясністю, будують довіру з часом. Фрази, наведені у цьому довіднику, є початковими пунктами — адаптуйте їх до свого голосу і норм вашої команди.

Навигація нюанс: фрази для конструктивного зворотного зв’язку в командному режимі

Надання зворотнього зв’язку - особливо про код - може відчуватися неймовірно делікатним. Легко ненавмисно звучати критичним або залишити когось невпевненим у тому, що ви насправді хочете, щоб вони робили. Велика частина ефективного спілкування - це вибір правильних слів, і це особливо важливо, коли потрібно керувати культурними відмінностями в команді. Для не-рідних англомовних носіїв, це може бути підсилене тривогами навколо виразності. Давайте розглянемо деякі конкретні фрази і підходи, які будують довіру і заохочують вдосконалення, зосередившись на тому, як оформити пропозиції як запрошення, а не як директиви.

Однією з поширених проблем є просто заявляти, що не так, не пропонуючи рішення. Замість того, щоб сказати « Цей код заплутає », спробуйте сказати щось на зразок: « Мені здається, що цей розділ трохи занадто густий — чи не могли б ми, можливо, розглянути його за допомогою більшого числа коментарів, щоб прояснити логіку? » Зауважте використання слова « Я вважаю », яке пом’якшує твердження і робить його стосовно вашого розуміння, а не об’ єктивного судження. Іншою корисною фразою є « Чи було б корисно, якби я пройшов цей шлях з вами? » Цей спосіб пропонує допомогу безпосередньо і запрошує до співпраці. Аналогічно, при вказівці на потенційну проблему, такі фрази як «Може бути корисно розглянути…» або «Може ми могли б дослідити…» є набагато менш конфронтаційними, ніж пряма критика. При обговоренні технічного боргу, уникайте обвинувальної мови; замість цього, оформляйте його як можливість: «Ця область здається зрілою для рефакторингу - чи ви будете відкриті до обговорення того, як ми можемо поліпшити її підтримку?»

Слабкі розмови часто вимагають такого ж рівня такту. Отримавши тупий коментар через Slack, можна відчувати себе особливо незручно, особливо якщо тон не відразу зрозумілий. Замість того, щоб реагувати оборонно («Це не допоможе!»), спробуйте визнати зворотній зв’ язок і попросити про пояснення: «Дякую за пояснення! Чи могли б ви розібратися, що саме ви сподівались змінити тут?» Це демонструє відкритість і бажання зрозуміти їхню точку зору. Пам’ятайте, що будівництво відносин через обдумане спілкування має вирішальне значення - навіть невеликі жести можуть зробити велику різницю в тому, як ваш відгук буде прийнятий. Нарешті, завжди закінчуйте позитивною нотаткою: «Я ціную ваш внесок; давайте працювати разом, щоб забезпечити, що цей код відповідає нашим стандартам»