Як обговорювати якість коду англійською мовою

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

Ключові фрази

** Опис складності: **

• Це збільшує цикломатичну складність функції — вона вже має вісім гілок
• “Когнітивна нагрузка тут висока. Мені довелося прочитати це три рази, щоб зрозуміти, що це робить»
• «Я б витягнув це в окрему функцію, щоб зробити намір яснішим»
• «Цей метод робить занадто багато — він порушує принцип єдиної відповідальності»

** Визначення проблем проектування: **

• «Існує порушення принципу єдиної відповідальності тут — цей клас обробляє як автентифікацію, так і ведення журналу»
• «Ця модель є крихкою, тому що вона залежить від внутрішнього стану іншого модуля»
• «Ми маємо тісне з’єднання між цими двома службами — зміна в одній, ймовірно, порушить іншу»
• «Рівень абстракції є непослідовним — деякі методи є високорівневими, в той час як інші є деталями реалізації»

** Пропозиції щодо поліпшення: **

• «Я б витягнув це в окремий модуль, щоб поліпшити тестованість»
• «Давайте націлимося на більшу сплоченість в цьому класі і нижче з’єднання з його залежностями»
• Чи можемо ми замінити це твердження про перемикач стратегічним шаблоном?»
• Я б розглянув використання залежності введення тут, щоб зробити це легше перевірити в ізоляції. ”

** Конструктивное оформление отзыва: **

• «Це працює, але я хвилююся про підтримку, оскільки кодова база зростає»
• «Я бачу, що ви тут робите — чи варто розглядати альтернативу, де…»
• “Nit: ця назва змінної могла б бути більш описовою. Не блокатор, а просто пропозиція»
• «Це блокує мене — відсутність обробки помилок може призвести до тихих невдач у виробництві»

Як це використовувати на практиці

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

• ** Блокер / Потрібно виправити ** — « Це блокер — він призведе до втрати даних у крайніх випадках. »
• ** Слід виправити ** — « Я б хотів, щоб ми вирішили це питання перед злиття — зв’ язок тут зробить майбутні зміни болючими. »
• ** Nit (nitpick) ** — « Nit: незначна проблема зі стилем, не блокує »
• ** Suggestion ** — « Необов’ язковий: просто щось, що варто враховувати під час майбутнього перероблення. »

Наведіть у своєму повідомленні префікс « Nit: » або « Suggestion: », щоб автор знав, наскільки критичним ви вважаєте цей запит. Це стандарт у командах Google, Meta і багатьох великих технологічних компаній.

Коли ви кажете, що щось « збільшує цикломатичну складність », ви стверджуєте, що у нього занадто багато незалежних шляхів коду (гілок, петель, умов). Ви можете зробити це конкретним: “Ця функція має цикломатичну складність 14. Все, що вище 10, стає важко перевірити вичерпно»

** Сплоченість ** стосується того, наскільки тісно пов’ язані відповідальності у межах модуля. Висока сплоченість є хорошою — все в модулі належить разом. ** Сполучення ** стосується того, наскільки модулі залежать один від одного. Низьке з’ єднання є хорошим — модулі можуть змінюватися незалежно.

Приклад розмови

Рецензент (Максим): “Я залишив кілька коментарів на PR. Головним з них є блокування — логіка автентифікації і сповіщення електронною поштою виконують одну і ту ж функцію, що є порушенням принципу єдиної відповідальності. Якщо нам потрібно змінити постачальника електронної пошти, ми повинні торкнутися коду автентифікації»

“Хороший пойманий. Чи було б сенсом витягнути повідомлення в окремий клас служби?»

Максим: “Так. Це дасть нам нижче з’єднання і зробить обидві частини незалежно тестовими. Я також залишив ніт про змінні назви в петлі — не блокер, але назва i не передає багато намірів при ітерації над userRecords.”

Автор: “Згоден. Я перейменую його на userRecord і витягну логіку повідомлення перед запитом повторного перегляду»

Практичні поради

1. ** Перегляньте код на GitHub з урахуванням словника: ** Наступного разу, коли ви прочитаєте обговорення щодо запитів на витягнення у публічному сховищі (на GitHub є мільйони відкритих PR), підсвічуйте кожну фразу, яка описує проблему з якістю коду. Зверніть увагу, як носії мови розглядають блокувальники проти пропозицій.

2. ** Переписати нечіткий коментар у точний: ** Візьміть нечіткий коментар коду, наприклад, « це незручно », і перепишіть його за допомогою словника з цього повідомлення. Наприклад: «Це збільшує цикломатичну складність і порушує принцип єдиної відповідальності — я витягнув би логіку перевірки в окремий клас»

3. ** Вправлятися у розрізненні когерентності/ з’ єднання: ** Розгляньте два приклади з вашої власної бази коду — один, де когерентність є високою (модул, який добре виконує одну функцію), і один, де з’ єднання є високим (два модулі, які важко змінити незалежно один від одного). Опишете кожен приклад англійською мовою, використовуючи терміни з цього повідомлення.

Наприклад, англійська мова має спеціальний словник для не-національних носіїв

Ефективне обговорення якості коду не просто про те, що щось * потребує * поліпшення. Це дуже нюансований процес, що залежить від точного словника, який може здатися приголомшливим, особливо при вивченні професійної англійської. Багато розробників, особливо ті, чия перша мова не є англійською, борються з тонкими відмінностями в значенні і використанні, пов’язаними з технічними поняттями, такими як когезія, з’єднання або цикломатична складність. Розглянемо деякі з цих ключових областей, особливо для людей, для яких мова не є рідною, зосередившись на практичних сценаріях, з якими ви можете зіткнутися під час перегляду коду або обговорення.

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

Окрім окремих концепцій, звертайте увагу на фрази, що використовуються під час перегляду коду. Коментарі типу «це жахливо пахне» є неймовірно нечіткими і нецікаво. Замість того, щоб звертатися до суб’єктивних описів, націлюйтеся на конкретні спостереження, пов’язані з встановленими принципами. Наприклад, якщо ви обговорюєте цикломатичну складність, сказати “Цей метод має високу цикломатичну складність (n = 6), що, можливо, ускладнює його всебічне тестування” набагато більш дієвий, ніж просто зазначити, що він “складний”. Крім того, при запропонуванні змін в описах PR, зосередьтеся на впливі вашого запропонованого рішення. Замість того, щоб вказати « Виправити ваду », спробуйте: « Ця зміна вирішує потенційну проблему переслідування за допомогою введення блокування mutex, яке покращить послідовність даних і запобіжить несподіваним поведінкам. »

І, нарешті, не бійтеся просити про пояснення. Якщо ви не впевнені щодо терміну або фрази, використовуваних колегою, ввічливо запитайте про пояснення. Питання «Чи можете ви розібратися, що ви маєте на увазі під «SRP» в цьому контексті?» є цілком прийнятним - це демонструє вашу готовність навчатися і забезпечує, що всі знаходяться на одній сторінці. Пам’ятайте, чітке спілкування є найважливішим, і пошук роз’яснень є ознакою активного залучення, а не слабкості.