Англійська мова для перегляду коду: фрази, що працюють
Найефективніші англійські фрази для надання, отримання і відповіді на зворотній зв’ язок щодо перегляду коду — поділені на категорії за метою і тоном.
Ефективне обговорення коду є навичкою, відмінною від написання хорошого коду. Те саме технічне спостереження може бути доставлено таким чином, що мотивує автора, або таким чином, що створює тертя і обурення. У цьому підручнику ви знайдете англійські фрази, які дають найкращі результати у потоках перегляду коду.
Метою є ясність без тривоги
Перед тим, як обрати слова, запитайте себе: * Що я хочу, щоб сталося у результаті цього коментаря? * Більшість коментарів перегляду спрямовано на один з таких результатів:
- Автор виправляє певну річ
- Автор розглядає альтернативний підхід
- Ви розумієте, чому автор зробив вибір
- Автор відчуває підтримку, а не напад
Ваша мова повинна відповідати результату, який ви бажаєте отримати.
Вступні коментарі: Встановити тон
Коли ви починаєте перегляд, у короткому коментарі з обрамленням ви можете вказати очікування:
“В цілому це хороший PR — у мене є кілька пропозицій і одна необхідна зміна перед тим, як ми злитимемось.”
“Все добре. Большая часть этого выглядит отлично. Я залишив деякі питання, де я хотів би отримати пояснення.”
“Це велика зміна і я зробив усе можливе, щоб ретельно її переглянути. Я можу пропустити щось — щасливий обговорювати все, що я позначив.»
Такий тип відкриття зменшує захист перед тим, як автор прочитає будь- який конкретний коментар.
Потрібні зміни: Бути прямим, а не жорстким
Якщо щось потрібно виправити, будьте ясно налаштовані — але поясніть * чому*:
- « Це потрібно виправити перед об’ єднанням: помилка тут буде проковтнута беззвучно, це означає, що помилки не будуть помічені у виробництві. » *
- “Будь ласка, оновіть це: функція змінює вхідний параметр, що призведе до несподіваних побічних ефектів для викликаючих.” *
- “Це блокування — тест буде успішним лише тому, що імітаційний код занадто допустимий. Будь ласка, оновіть моку, щоб вона відповідала фактичному API-контракту.”*
Шаблон: зазначте, що потрібно змінити + поясніть наслідки. Це більш переконливо і освітньо, ніж просто команда.
Підказки: Позначте, що вони не обов’ язкові
- “Одна думка: ви можете уникнути вкладених умовних виразів за допомогою ранніх повернень. Це означає, що це працює добре, як-то є.”*
- “Розгляньте можливість перетворення цього регулярного виразу у названу константу — це зробить мету більш зрозумілою. Не блокування».*
“Це просто стиль, який ви хочете, не хвилюйтеся ігнорувати: я б назвав це
isLoading, а неloading, щоб відповідати нашій конвенції в інших місцях.”
Ключові сигнали: ** розглянути **, ** одна думка **, ** не соромтеся ігнорувати **, ** не блокувати **, ** просто переваги **.
Запитання без критичного висловлювання
“Я не впевнений, що я тут дотримуюсь логіки — чи можете ви розповісти мені, що відбувається, коли
retryCountдосягає свого обмеження?”
“Яка була причина вибору
Mapтут замість звичайного об’ єкта? Мені цікаво, чи є причина для виконання.»
“Чи можете ви допомогти мені зрозуміти це — чи є блок
finallyнавмисним, навіть якщо немаєcatch?”
- « Можливо, мені бракує контексту: чи викликається ця функція з будь- де, чи лише з цього модуля? » *
Фраза «Я можу не розуміти контексту» дуже корисна — вона сигналізує про інтелектуальну скромність і запрошує автора пояснити, а не захищати.
Відповідь на коментарі до перегляду
** Прийняття відгуку: **
“Ти маєш рацію - я пропустив це. Я натиснув на поправку.”
“Хороший пойманный. В останньому звіті оновлено
“Честный вопрос. Я переробив це і додав тест, щоб покрити цей випадок. ”
З повагою не погоджуюсь:
- “Я розумію, звідки ви прийшли, але я обрав цей підхід, тому що він збігається з тим, як ми обробляємо це у модулі платежу. Я щасливий змінити це, якщо ти сильно відчуваєш це»
“Це дійсна альтернатива. Моя проблема з цим - [причина]. Чи хотіли б ви обговорити це в короткому дзвінку?»
Прохання про пояснення щодо коментаря:
- “Чи можете ви розширити цей коментар? Я хочу переконатися, що я розумію, які зміни ви пропонуєте.»*
“Только для подтверждения: вы просите меня изменить структуру, или просто название?”
Завершення перегляду позитивно
“LGTM — хорошая чистая работа здесь.”
“Схвалено. Потрібна зміна виглядає добре після вашого оновлення.”
- “Щасливий об’ єднати, як тільки тест буде виправлено. Все інше виглядає твердо.»*
“Відмінна співпраця. Остаточна реалізація набагато краща, ніж оригінальний дизайн.»
Фрази, яких слід уникати
| Avoid | Why | Better alternative |
|---|---|---|
| ”Why did you do this?” | Sounds accusatory | ”What was the reason for this approach?" |
| "This is wrong.” | Vague and dismissive | ”This will cause X — please fix by doing Y." |
| "Obviously you should…” | Condescending | ”I’d suggest…" |
| "Just…” | Minimises effort | Remove it entirely |
| ”This is terrible.” | Unprofessional | ”This needs significant refactoring before merge.” |
Мова перегляду коду є професійним ремеслом. Інженери, які чітко і люб’язно повідомляють зворотній зв’язок, отримують свої пропозиції, які діють частіше - і будують сильніші команди в процесі.
Націоналізм: мова про окремі мови, що не є рідними для населення
Зрозуміти * чому * за коментарем перегляду коду часто так само важливо, як зрозуміти * що *. Для не-рідних носіїв англійської мови це може бути особливо складним. Багато фраз, які здаються простими для носіїв мови, мають тонкі конотації або граматичні складності, які можуть призвести до неправильного тлумачення і почуттів оборони. Давайте зосередимося на тому, як активно вирішувати проблеми, які виникають під час перегляду, особливо коли ви підозрюєте, що в грі може бути різниця в стилі спілкування.
Однією з поширених проблем є прямість, часто пов’язана з західними культурами зворотнього зв’язку. Фрази на кшталт «Це не компілюється» або «Це неефективне» можуть відчуватися різкими і критичним, навіть якщо вони мають конструктивний намір. Більш нюансований підхід починається з визнання перспективи рецензента. Спробуйте такі фрази, як: « Я дякую вам за те, що ви на це звернули увагу — чи не могли б ви розібратися, що саме робить цей процес неефективним? » Або, якщо ви зіткнулися з помилкою компіляції, скажіть: « Добре, давайте разом розв’ язаємо цю проблему. Чи можете ви поділитись точним повідомленням про помилку і де в коді вона відбувається? Це демонструє відкритість до навчання і співпраці, а не негайний опір. Аналогічно, якщо хтось пропонує рефакторинг, не кажуть просто «Ні». Замість цього, відповідайте щось на зразок: «Це цікава пропозиція - чи можемо ми обговорити компроміси між цим підходом і поточним? Можливо, є спосіб досягти тієї ж мети більш ефективно»
Крім того, важливо бути уважним до ідіом і поширених виразів. Фрази на кшталт «приберіть код» можуть здатися нечіткими. Замість цього, надайте конкретні пропозиції: « Чи не завадило б вам додати коментарі, які б пояснили логіку, яка лежить в основі цього розділу? » або « Чи не могли б ми розглянути можливість використання іншої структури даних, щоб поліпшити читабельність? » Також, не вагайтеся * запитати про пояснення *, якщо щось не зрозуміло. Просте запитання на кшталт: «Я не зовсім впевнений, що ви маєте на увазі під «супроводжуваністю» в цьому контексті - чи можете ви дати мені приклад того, що ви шукаєте?» показує справжнє бажання зрозуміти і вирівняти з очікуваннями рецензента. Нарешті, пам’ ятайте, що активне слухання - перефразування коментаря рецензента назад до них, щоб забезпечити розуміння - є безцінним. “Тоді, якщо я правильно розумію, ви турбуєтеся про потенційні проблеми масштабованості з цим підходом?” Цей простий акт може значно зменшити непорозуміння і сприяти більш продуктивному діалогу.