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