Англійська мова для перегляду коду: професійні фрази і словник
Практичний посібник з професійних фраз англійською мовою для коментарів щодо перегляду коду — від ввічливих пропозицій до сильних блокувань, зауважень і схвалень.
Перегляд коду є однією з найбільш текстових форм комунікації в розробці програмного забезпечення. На відміну від розмовної розмови, ваші письмові коментарі є постійними, асинхронними і читаються без урахування тону голосу або виразу обличчя. Тому вибір слів дуже важливий. Погано сформулований коментар може звучати агресивно, коли він має бути корисним, або нечітко, коли він повинен бути вирішальним. У цьому підручнику наведено англійські фрази і словниковий запас, які вам слід знати, щоб писати коментарі щодо перегляду коду, які будуть ясними, професійними і конструктивними.
Розглядається питання про оцінку цінності
Перед написанням будь- якого коментаря до огляду, слід визначити, який саме тип коментаря це. Більшість команд розрізняють три категорії:
- ** Блокер (проблема блокування): ** Потрібно розв’ язати перед тим, як можна буде об’ єднати код. Вказує на дефект, проблему безпеки, проблему з коректністю або порушення критичного стандарту.
- ** Nitpick (nit): ** Невеликий, не блокуючий стилістичний параметр. Автор може взяти його або залишити. Зазвичай префіксується
nit:. - ** Пропозиція (не блокування): ** Справжня ідея покращення, яку автор повинен розглянути, але рецензент не наполягає на цьому.
Визначивши, який тип ви пишете, ви збережете значну кількість часу на обмін повідомленнями.
Таблиця посилання на фразу
| Comment Type | Example Phrase |
|---|---|
| Blocker — correctness | ”This will cause a race condition when two requests hit this simultaneously.” |
| Blocker — security | ”This exposes the raw database error message to the client — this needs to be sanitised before merge.” |
| Blocker — logic | ”This condition is inverted — as written, this will fail for the majority of valid inputs.” |
| Suggestion — refactor | ”Consider extracting this into a separate method — it would make the logic easier to follow and easier to test.” |
| Suggestion — naming | ”The name data is a bit generic here. Something like userPreferences might communicate intent more clearly.” |
| Question — clarification | ”Could you help me understand the reasoning here? I want to make sure I’m not missing something.” |
| Question — simplification | ”Could we simplify this logic? It looks like the inner conditional could be collapsed.” |
| Nitpick — style | ”nit: this could be written more concisely as a single expression, but I’ll leave it to you.” |
| Nitpick — naming | ”nit: minor naming inconsistency with the rest of the module — not blocking but worth noting.” |
| Praise | ”Nice approach here — this is a much cleaner solution than what we had before.” |
| Approval | ”LGTM. A couple of minor nits above but nothing blocking.” |
Писати ввічливі, але чіткі пропозиції
Найбільш поширеною помилкою у перегляді коду англійською мовою є надто нечітка або надто тупа мова. « Це неправильно » — це тупий вираз. « Не впевнений у цьому » — це надто тупий вираз, щоб бути корисним.
Хороша мова пропозицій має три компоненти: ** спостереження **, ** обґрунтування ** і ** альтернатива ** (необов’ язково).
Examples
Занадто неопределенно
«Це виглядає неправильно»
Занадто тупо
Це неправильно»
** Добре сформована пропозиція: **
«Ця петля ітерує по всьому масиву при кожному виклику — розгляньте кешування результату поза петлею, щоб уникнути O(n²) складності.»
** Директива To: **
Змінити назву змінної
** Добре сформована пропозиція: **
«Розгляньте перейменування
tempна щось, що описує те, що він містить — мені знадобилося кілька хвилин, щоб зрозуміти його призначення»
Слово ** розглянути ** є одним з найкорисніших слів в англійській мові перегляду коду. Це означає рекомендацію без надання мандата. Аналогічно, такі фрази як «це може бути варте…», «один варіант був би…», і «ви також могли б…» сигналізують про пропозицію, а не про інструкцію.
Використовується для блокування повідомлень
Якщо перед об’ єднанням потрібно щось виправити, ясність важливіша за плавність. Захищення блоку створює плутанину щодо того, чи є коментар обов’ язковим чи необов’ язковим.
Блокування фраз
- Це викликає витік пам’яті — слухач ніколи не буде видалений
- «Блокування: цій кінцевій точці бракує автентифікації — це може відкрити дані користувача для неавтентифікованих запитів»
- Це призведе до невдачі в виробництві — змінна середовища не встановлена в конфігурації розгортання
- Це проблема коректності: функція повертається раніше, ніж буфер запису буде спустошений
Зауважте використання will замість could або might — це сигналізує про певність, а не можливість. Для справжніх блокаторів, будьте прямими.
Запитання, що не викликають жодних сумнівів
Питання часто є більш ефективними, ніж заявки в перегляді коду, тому що вони запрошують пояснення, а не оборону. Однак, слово має значення.
Аккузативний (уникайте):
Чому ти зробив це таким чином?»
Нейтрально и любопытно:
“Чи можете ви допомогти мені зрозуміти, що стоїть за цим підходом? Я хочу переконатися, що я не пропускаю обмеження»
** Відкриття дискусії: **
«Я можу помилятися тут, але я думав X — чи це змінює це припущення?»
** Перевіряю ваше розуміння: **
«Тільки щоб підтвердити моє розуміння: ця функція викликається тільки в однопоточному контексті, чи не так?»
Затвердження та LGTM мова
«LGTM» (Looks Good To Me) — стандартний сигнал схвалення в англомовних кодових оглядах. Ось варіанти з різними нюансами:
- “LGTM.” — чисте, безумовне схвалення.
- ** « LGTM — декілька незначних помилок вище, але нічого не блокує ». ** — Затвердження з вказівником на коментарі, які не блокують.
- ** « Затверджено з незначними коментарями — приємно, що ви змогли об’ єднати після того, як ви вирішили проблему з нит у функції
processOrder. » ** — Затвердження залежить від певної, некритичної зміни. - ** « Виглядає добре, на мою думку — добре структурована зміна. » ** — Написано повністю, трохи більш формально, може містити коротку позитивну ноту.
Слов’янська мова
Похвала під час перегляду коду створює позитивну культуру команди і варто її робити, якщо ви справді це маєте на увазі:
- «Справді чисте рішення тут — набагато легше дотримуватися, ніж попередня реалізація.»
- «Я був вражений, коли побачив, що це було зроблено на початку»
- «Нічне використання шаблону стратегії — це зробить легким додавання нових постачальників платежів пізніше.»
- «Ця тестова програма є досконалою — хороший огляд сценаріїв невдач»
Встановлення мовлення в асинхронному режимі
Оскільки коментарі перегляду коду читаються без контексту звуку, вони можуть здатися жорсткішими, ніж це було призначено. Декілька порад, які допоможуть:
- **Відповідайте за спостереження, а не за судження. **Скажіть, що ви помітили, перш ніж сказати, що ви про це думаєте.
- ** Використовуйте « Я », де це потрібно. ** « Мені це важко зрозуміти » розуміється по- іншому, ніж « це важко зрозуміти. »
- ** Підтверджуйте, коли ви не впевнені. ** Фрази на зразок « Я можу помилятися » або « Я не на 100% впевнений, але… » зменшують ризик авторитетного коментаря, який виявиться неправильним.
- ** Відокремлюйте ключові слова від блокуючих їх слів** — або за допомогою префіксів (
nit:,blocking:), або за допомогою звичайного тексту.
Ключеві моменти
- Класифікувати кожен коментар як ** блокування, пропозицію або неприйнятний коментар ** — зробіть це явним.
- Використовуйте “consider” і “може бути варте” для пропозицій; використовуйте “буде” і пряму мову для блокувань.
- Питання на кшталт “Чи можемо ми спростити…?” і “Чи можете ви допомогти мені зрозуміти…?” є більш ефективними, ніж тупі висловлювання.
- LGTM, «Схвалено з незначними помилками», і мова похвали мають різні ролі в огляді.
- В асинхронному письмовому спілкуванні точність і контроль тону важливіші, ніж в усній розмові.
Навигація нюансами: вирішення потенційних проблем проактивно
Будьмо чесними - перегляд коду іноді може відчуватися трохи напруженим. Навіть з найкращими намірами, надання зворотнього зв’язку - особливо критичного зворотного зв’язку - може бути складним, особливо коли ви звикли до іншого стилю спілкування або якщо технічна область є незнайомою територією. Ключовим елементом професійної англійської мови в цьому контексті є не тільки використання точної термінології, але і передбачення потенційних проблем і їх активне вирішення. Це демонструє повагу до часу і досвіду вашого рецензента, а також сприяє більш спільному середовищу. Це не про те, щоб негайно вказувати на недоліки; це про те, щоб підготувати сцену для конструктивної дискусії.
Одна з поширених областей нерозуміння - це фрази, які можуть здатися надто директивними. Замість того, щоб сказати «Це потрібно переробити», що може звучати як осудження, подумайте про щось на зразок: «Мені цікаво, чи можемо ми дослідити альтернативні підходи тут — можливо, зосередившись на [спеціальному аспекті], щоб поліпшити читабельність і підтримку в довгостроковій перспективі». Це пом’якшує пропозицію поясненням * чому * ви її піднімаєте. Аналогічно, коли ви стикаєтеся зі складним розділом, не просто скажіть « Це заплутано ». Краще буде сказати: « Мені здається, що цей розділ на перший погляд трохи складно зрозуміти. Чи можемо ми додати короткий коментар, який пояснює [конкретну концепцію], або змінити її структуру для більшої ясності?» Якщо ви ставитеся до вашого відгуку як до запрошення до обговорення, а не як до вимоги змін, це значно зменшить ваші захисні можливості.
Кроме того, не недооценивай силу признания усилий. Якщо ви бачите, що хтось зробив значний внесок у роботу і просто потребує невеликого полірування, просто « Це виглядає дуже добре! Лише кілька дрібних моментів…» може пройти довгий шлях. Це підтверджує їхню важку роботу і встановлює позитивний тон для огляду. Аналогічно, коли ви відкидаєте потенційно проблематичне рішення - можливо, те, що не повністю відповідає встановленим стандартам кодування - починайте з визнання його заслуг: “Я ціную те, що ви вирішили цю проблему; це розумне рішення! Я лише трохи хвилююся щодо [конкретного аспекту] і чи може це вплинути на [зв’язану область]». Це демонструє, що ви ретельно розглянули пропозицію, перш ніж висловити свої застереження. Пам’ятайте, ефективне спілкування часто стосується будівництва мостів, а не встановлення бар’єрів.
Нарешті, при обговоренні потенційних ризиків - особливо навколо безпеки або продуктивності - будьте надзвичайно ясними і конкретними. Уникайте нечітких тверджень на кшталт « Це може бути проблемою ». Замість цього, сформулюйте * точно *, що таке ризик: « Я хвилююся, що цей підхід може ввести вразливість до [особливого типу атаки], якщо не поводитися обережно. Чи можемо ми дослідити [альтернативне рішення] для посилення безпеки?” Продемонструвати технічне розуміння і проактивно описати потенційні наслідки показує професіоналізм і зменшує ймовірність нерозуміння, що призводить до серйозних проблем.