Розробник відкриває пул-реквест, який додає розрахунок знижки до сервісу оформлення замовлення. Тести проходять успішно, і різниця невелика. Рецензент схвалює його за дві хвилини з "LGTM". Через три місяці колега по команді має змінити ту саму функцію та виявляє, що вона змішує правила ціноутворення, округлення та доступ до бази даних в одному місці. Ніхто не може з упевненістю сказати, що їй дозволено робити.
Це ілюстративний сценарій, а не задокументований інцидент. Він показує, що має створити експертна оцінка коду, коли вона працює як навчальна діяльність: рецензент, який може побачити правдоподібну зміну, виявити проблему, яка ще не є помилкою, і пояснити її таким чином, щоб автор міг діяти відповідно.
Цей посібник призначений для керівників інженерних відділів та менеджерів з інженерних розробок. Він показує, як проектувати вправи з перевірки коду які навмисно розвивають цю навичку, а не сподіваються, що рецензенти підберуть її з черги. Вона охоплює проблему продуктивності, прогалини, які потрібно діагностувати, як структурувати підготовку та практику, один робочий приклад та як перевірити, чи переноситься навичка на реальні рецензії. Нехай старші інженери перевірять кожен випадок, дефект та критерій, перш ніж використовувати його.
Що таке вправи з перевірки коду?
Вправи з перевірки коду – це структуровані практичні завдання, в яких розробник переглядає підготовлену зміну, пояснює, що він знайшов і чому це важливо, а також отримує відгук про якість цього пояснення. Вони відрізняються від оглядів, які ваша команда проводить щодня. Зміна обирається заздалегідь, проблеми, що її містять, відомі, а метою є покращення рецензента, а не його відправка.
Швидкі факти
| Питання | Коротка відповідь |
|---|---|
| Яке завдання? | Поясніть результати огляду та надайте відгук, на основі якого автор може вжити заходів. |
| Який бал ви отримуєте? | Точність результатів та корисність пояснення. |
| Чи достатньо підрахувати дефекти? | Ні. Відгуки стосуються не лише дефектів, тому вправа, яка винагороджує лише кількість помилок, виховує неправильну звичку. |
| Що таке когнітивний попит? | Проаналізуйте та оцініть дизайн, а потім створіть кращу пропозицію. |
| Хто підтверджує справу? | Керівник інженерної служби або старший інженер, який володіє кодовою базою. |
| Чого не можуть виправити вправи? | Час розгляду, нечіткість питань власності та тиск на швидке об'єднання. |
| Звідки ви знаєте, що це спрацювало? | Нова, невідома зміна, перевірена на відповідність узгодженим критеріям, а також подальші дії на основі реальних відгуків. |
1. Опишіть проблему продуктивності
Почніть із завдання одним реченням: якщо є зміна, рецензент пояснює, що він знайшов, чому це важливо та що автор може з цим зробити. «Пояснює» – ось головне слово. Виявлення проблеми – це половина майстерності. Сказати це так, щоб колега з іншою точкою зору міг її зрозуміти, зважити та діяти – це інша половина.
Дослідження сучасного перегляду коду підтверджують необхідність виходити за рамки простого пошуку помилок. У дослідженні, проведеному в Microsoft, Баккеллі та Берд спостерігали, інтерв'ювали та опитували розробників і менеджерів. Вони виявили, що пошук дефектів все ще є основною мотивацією для перегляду, але перегляди менше стосувалися дефектів, ніж очікували люди. Вони також приносили інші переваги, такі як обмін знаннями, обізнаність команди та альтернативні рішення, а дослідники описали розуміння коду та змін як ключовий аспект перегляду (Баккеллі та Берд, ICSE 2013). Це дослідження команд однієї компанії, тому використовуйте його як причину для розробки для розуміння, а не як ціну для вашої.
Опублікований стандарт рецензування Google вказує на те саме. Він радить рецензентам схвалювати зміни, якщо вони однозначно покращують загальний стан коду, навіть якщо він не ідеальний, і стверджує, що рецензування може навчити розробників чогось нового, тому коментарі, які допомагають комусь навчатися, вітаються (Інженерні практики Google). Обидва джерела описують огляд як місце, де здійснюється та виноситься судження. Саме це мають відпрацьовувати ваші вправи.
2. Діагностуйте прогалини у навчанні та контексті
Порівняйте завдання з тим, що практикується та оцінюється у вашій поточній програмі.
- Чи використовує сучасна практика реальне завдання? Якщо нові рецензенти навчаються, читаючи посібник зі стилю, а потім переглядаючи реальні пул-реквести, вони практикуються на реальній роботі, не маючи безпечного місця для помилок. Якщо оцінювання — це тест на етикет рецензування, він вимірює запам'ятовування правил, а не здатність застосовувати їх до зміни.
- Що таке когнітивний попит? У переглянутій таксономії Блума оцінка надійності дизайну та зважування його недоліків здійснюється на рівнях аналізу та оцінки, а пропонування кращої структури сягає рівня створення. Якщо ваші вправи запитують лише «що робить цей код?», вони зупиняються на розумінні. Наш посібник з зіставлення навчальних завдань з таксономією Блума показує, як узгодити діяльність з рівнем.
- Чи щось, окрім навичок, заважає? Перевірте час перевірки, інструменти, власників та норми роботи команди. Якщо рецензенти мають п'ять хвилин на кожен запит на внесення змін, жодна вправа не призведе до вдумливого пояснення. Якщо автори сприймають кожен коментар як критику, рецензенти пом'якшуватимуть свої висновки, поки не промовчать. Повідомте про ці причини людям, які можуть їх виправити.
3. Підготовка дизайну, практика та зворотний зв'язок
Дайте кожному етапу окреме завдання.
Підготовка. Перевірте, що потрібно рецензентам, перш ніж розпочати: контрольний список команди для перевірки, принципи дизайну, на які вона спирається, та як читати відмінності у вашому інструментарії. Робіть це у власному темпі та коротко. Перевірка відкликання підтверджує лише передумови, і вона не є доказом того, що хтось може перевірити.
Практика. Використовуйте підготовлені зміни з невеликою кількістю початкових проблем різного характеру: помилка коректності, проблема підтримки, така як змішані обов'язки у початковому прикладі, незрозуміла назва або відсутній тест, а також деякий код, який є нормальним. Попросіть рецензента написати коментар, який він би залишив, оцінити проблеми та вказати, яку додаткову інформацію він хотів би отримати. Практичний урок CodeRefinery показує, як це працює: люди відкривають запит на втягування, що містить невелику друкарську помилку та більшу помилку, а потім рецензують його як колега (CodeRefinery, Практика перегляду коду). Створіть свій на основі власної кодової бази, щоб дотримувалися умовностей та компромісів.
Зворотний зв'язок. Пов’яжіть це з рішеннями, які прийняв рецензент. «Ви помітили проблему округлення, але у вашому коментарі було написано «це виглядає неправильно», не вказавши, які вхідні дані порушують це» корисніше, ніж «знайдено 2 з 4».
Живий ввід чи асинхронний огляд? Жива відповідь найбільш цінна, коли питання неоднозначне, і рецензенти дізнаються, почувши від старшого інженера, чому вони його порушили, або відпустивши його. Асинхронного рецензування достатньо для порівняння коментарів з анотованим експертним оглядом.
4. Розгляньте реалістичний приклад
Ілюстрація. Керівник інженерного відділу повинен перевірити кейс та критерії відповіді перед використанням.
Справа. Зміна додає розрахунок знижки до сервісу оформлення замовлення. Він проходить тести. В одній функції застосовується відсоткова та фіксована знижки, округляється результат, записується в базу даних та надсилається подія. Він має один тест – для знижки в один відсоток.
Завдання. Рецензент записує коментарі, які вони залишать, ранжує їхні зауваження та повідомляє, що їм потрібно знати перед схваленням.
Перша спроба. «Виглядає добре, тест пройдено. Можливо, варто розділити його?» Рецензент щось помітив, але не сказав, що саме, чому це важливо або що робити. Автор не може з цим вдіяти.
Зворотній зв'язок та повторна спроба. Фасилітатор запитує: які зміни в цій функції можуть призвести до збою? Що б ви попросили автора додати перед схваленням? Під час повторної спроби запитується конкретний коментар щодо кожного занепокоєння, з причиною та пропозицією.
Сильніша спроба. «Функція застосовує два види знижок: округлює, зберігає та публікує подію, тому зміна округлення може одночасно змінити те, що ми зберігаємо, і те, що ми публікуємо. Я б попросив перенести правила ціноутворення в чисту функцію, яку ми можемо протестувати самостійно. Один тест охоплює лише відсоткову знижку. Я б попросив фіксовану знижку та замовлення, яке доводить загальну суму до нуля. Я не впевнений, чи подія має спрацьовувати, коли загальна сума дорівнює нулю, тому я б запитав автора». Зверніть увагу, що в цьому коментарі названо проблему, наведено причину, зроблено конкретну пропозицію та зазначено те, чого рецензент не знає.
5. Оцінка можливостей та планування передачі
Доказом спроможності є виконання нової зміни, яку рецензент ще не бачив. Оцініть точність результатів та корисність пояснення. Проста рубрика використовує шкалу від 0 до 2 за кожен критерій:
| критерій | Спостережувані докази |
|---|---|
| Виконання завдання | Знаходить відповідні проблеми у зміні та фіксує докази для кожної з них. |
| Обґрунтування | Пояснює, чому кожне питання важливе, пропонує альтернативу та вказує на те, що залишається невизначеним. |
| Межі | Дотримується правил команди щодо рецензування та просить допомоги або інформації, коли бракує авторитетності чи контексту. |
Опорні точки: 0 означає відсутність або непідтвердження, 1 означає часткове з відповідними пропусками, а 2 означає повне та обґрунтоване відповідно до узгоджених критеріїв. Визначте критичні помилки окремо, наприклад, схвалення зміни з ризиком втрати даних, щоб хороший загальний бал не міг його приховати. Адаптуйте критерії разом з керівником інженерного відділу; ця рубрика є початковою пропозицією, а не затвердженим стандартом готовності. Щоб дізнатися більше про міркування щодо оцінювання, див. наш посібник розробка інтерактивної практики з корисним зворотним зв'язком.
Плануйте перенесення. Після вправи перевірте вибірку реальних відгуків рецензента через кілька тижнів, використовуючи ті самі критерії. Порівняйте з базовим рівнем, взятим до навчання, та заздалегідь визначте сукупність учасників та часові рамки. Перш ніж зараховувати результати вправ, зверніть увагу на інші зміни, що відбулися за той самий період, такі як новий інструмент для рецензування або зміни в штаті.
6. Виконуйте вправу в прямому ефірі або у власному темпі за допомогою AhaSlides
Ви можете виконати вправу на семінарі або дозволити рецензентам самостійно її опрацювати. Під час живої сесії покажіть підготовлену зміну та використовуйте інтерактивні слайди для обговорення:
- Виберіть відповідь для питання «яке занепокоєння ви б порушили першим?», вказавши перші занепокоєння як варіанти. Покажіть розкид, перш ніж розкривати власний рейтинг.
- Відкритий закінчився для «напишіть коментар, який ви б залишили». Рецензенти можуть порівняти свої формулювання з іншими, і саме тут проявляється майстерність пояснення.
- Шкала оцінки на запитання «наскільки це серйозно?», щоб група могла побачити, де судження розходяться, та обговорити, чому.
Для рецензентів, які не можуть бути присутніми, та сама послідовність може бути використана у власному темпі, з анотованим експертним оглядом, що відображається після кожної відповіді. Будь-яке твердження щодо виконання коду, інтеграції або функцій штучного інтелекту слід розглядати як непідтверджене, доки ви не перевірите його на власному матеріалі.
Якщо ви також навчаєте рецензентів роботі з кодом, написаним за допомогою штучного інтелекту, див. наш супровідний посібник про Навчання з перевірки коду, згенерованого штучним інтелектомЦей пост про аудит згенерованих результатів. Цей про те, як люди перевіряють роботу один одного та як вони пояснюють свої висновки.
Обмеження, які можуть залишитися
- Час огляду. Вдумливий коментар займає більше часу, ніж "LGTM", а терміни скорочуються до коротшої версії.
- Командні норми. Якщо відгук сприймається як особиста критика, рецензенти пом'якшать або відкинуть свої висновки.
- Покриття справ. Одна вправа демонструє кілька видів занепокоєння. Оцінка не описує судження рецензента загалом.
- Трансфер Продуктивність у майстерні не те саме, що продуктивність у щільній черзі, тому також перевірте реальні відгуки.
Заздалегідь назвіть їх спонсорам та сплануйте окремі виправлення. Вправи покращують те, що рецензент може побачити та пояснити. Вони не створюють часу чи норм.
Часті питання
Що таке вправи з перевірки коду?
Це підготовлені практичні завдання, в яких розробник переглядає зміну з відомими зауваженнями, пише коментарі, які він би залишив, та отримує відгуки щодо точності та корисності. Мета полягає в тому, щоб розвинути навички рецензента, а не в тому, щоб відправити зміну.
Як ви оцінюєте, чи покращилася судження рецензента?
Назвіть нову зміну, якої вони не бачили, та оцініть висновки та пояснення за узгодженими критеріями. Потім перевірте вибірку реальних відгуків через кілька тижнів. Вікторина з правил рецензування підтверджує лише передумови.
Чи є експертна оцінка коду переважно метою пошуку помилок?
Пошук дефектів все ще залишається основною мотивацією, але одне дослідження, проведене в Microsoft, показало, що огляди менше стосувалися дефектів, ніж очікувалося, а також забезпечували обмін знаннями та підвищення обізнаності команди. Розробляйте вправи, які винагороджують пояснення та розуміння, а також кількість дефектів.
З чого почати
Виберіть один тип змін, який ваша команда часто переглядає. Напишіть звіт про ефективність, попросіть старшого інженера підготувати одну зміну з трьома або чотирма основними проблемами та складіть рубрику з трьома критеріями за шкалою від 0 до 2 та списком критичних помилок. Випробуйте її з невеликою групою, а потім порівняйте їхні наступні реальні огляди з базовим рівнем.
Щоб побачити, як вправу з огляду можна виконати в режимі реального часу з вашою командою та використовувати повторно у власному темпі згодом, ознайомтеся з AhaSlides.
