Код-ревʼю з двох кінців: як підготувати свій код та провести ревʼю чужого

Усі статті, обговорення, новини для початківців — в одному місці. Підписуйтеся на телеграм-канал!

Усім привіт! Мене звуть Данило Толмачов, я Full-Stack розробник та Team Lead в Techstack. За понад 10 років професійного досвіду я провів тисячі код ревʼю (CR) для різних стеків та мов програмування, а також, звичайно, багато разів готував свій код до ревʼю. Спираючись на це, я виявив загальні правила код-ревʼю та сформував декілька підказок, що допоможуть уникнути помилок.

Тож сьогодні поговоримо, як влаштований CR, як підготувати свій код, а також дати зворотний зв’язок, коли ви знаходитесь у ролі ревʼюєра. Через те, що зазвичай одній людині доводиться одночасно виступати як автор коду та як ревʼюєр для коду колег, то інформація у цій статті буде корисна для всіх, хто працює з кодом.

Навіщо потрібен CR

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

Перш ніж переходити до принципів підготовки та проведення CR, потрібно розібратися, навіщо цей процес потрібен. Причин є декілька. Зокрема, CR допоможе:

1. Уникати дрібних помилок, у тому числі і через неуважність. Кожному потрібні очі, які можуть оцінити ваш код, якщо ви щось пропустили або недогледіли. Описка, не переданий параметр у функцію чи метод — все це може помітити інша людина, коли ви вже не можете бути достатньо уважним.
   
2. Отримувати погляд від людей з досвідом, відмінним від вашого. У кожного з нас у багажі є унікальний досвід, якого немає в інших. Якщо на ваш код подивиться людина з іншим бекграундом, вона зможе привнести нові ідеї та рішення. Корисним може бути віддати код на ревʼю тому, хто працював на проєкті до вас і може розказати, які базові принципи були закладені при його створенні. Також гарною ідеєю буде показати код людині, що має досвід в іншій індустрії (наприклад, якщо ви працюєте над healthcare-продуктом, а ваш ревʼюєр — з фінансовим). Така людина може підказати вам рішення, що не є розповсюдженими в індустрії вашого продукту, але добре підходять для вирішення його проблем.

1. Обмінюватися досвідом і бути на одній хвилі. Добре, коли люди в команді можуть підтримувати та підміняти одне одного. Знаючи код, що пишуть ваші колеги, ви зможете набагато легше почати працювати в тій самій зоні, якщо доведеться. Так само й вони зможуть швидко та безболісно перейти в зону вашої роботи за потреби.

Тож не ігноруйте CR та не бійтесь його. Витрачена година часу зараз на рев’ю збереже нерви й заощадить години на підтримку в майбутньому.

Як підготувати ваш код до ревʼю

Ваша участь як автора у CR не зводиться до простого написання коду. Поважайте свого ревʼюєра та готуйтесь до цього процесу. Зробіть так, щоб він пройшов з максимальною користю як для вас, так і для ревʼюєра. Як саме?

• Автоматизуйте все, що можете. Спрощуйте все: використовуйте статичні аналізатори, які допомагатимуть виявляти code smells і security vulnerabilities, раннери, що запускатимуть усі тести (unit, integration, E2E, etc.), і style guides, що позбавлять вас потреби думати про розстановку крапок і ком. Автоматизація підвищить якість вашої роботи, заощадить час і допоможе змістити фокус рев’юера з перевірки самого коду на його відповідність бізнес-проблемам, які код має вирішувати.
• Уникайте «by the way changes». Подавайте на ревʼю лише те, що прописано у тасці, та не путайте вашего ревʼюєра. Це не значить, що ви не повинні покращувати той енвайронмент, в якому ви працюєте. Це значить лише те, що все повинно бути добре систематизовано та пов’язано. Якщо ви бачите баг, що не стосується ані зони, де ви працюєте, ані коду, якого ви торкаєтесь, заведіть окремий таск або тех дебт, і запускайте його у процес окремо.
• Документуйте свій код. Код є найважливішим поясненням того, як працює та чи інша фіча. Він вже сам по собі може багато вам розповісти. Тому для того, щоб він максимально ефективно пояснював себе сам, не забувайте коментувати та оновлювати його документацію, приділяйте увагу його структурі та назвам, які використовуєте. Коли ви пишете код — ви використовуєте мову. Тому ваш код повинен розповідати історію того, що виконується та як.
• Зменшуйте всі пул-реквести. Декомпозуйте свій код та тримайте пул-реквести у розмірі до 500 рядків бізнес-коду. За даними дослідження Smart Bear & CISCO, перевірити навіть понад 300-400 рядків коду без відволікань та отримання додаткової інформації якісно не вдається.

  З мого досвіду, 500 рядків бізнес-коду (без коментарів, нью-лайнс та форматування) — це максимальний розмір, який можна якісно обробити на ревʼю. Тому рекомендую з повагою ставитись до ревʼюєра та не пропонувати йому оглянути більше цього обсягу.

• Проревʼюйте свій код самостійно. Автор — це перший ревʼюер. Ставтеся до цього процесу дуже прискіпливо та критично. Намагайтесь абстрагуватися від того, що цей код був написаний вами, і не робіть собі поблажок чи знижок. Поставте себе на позицію рев’юера й огляньте свій код так, як би це робив він. Якщо у вас самих виникли питання до цього коду, запишіть його як коментар на платформі та потім вже як автор надайте відповідь. Такий підхід відразу додає прозорості.

Як виконувати CR

Тепер поставимо себе на сторону ревʼюєра та спробуємо розібратися, якими принципами керуватися, коли вам треба дати зворотний зв’язок на чужий код.

• Будьте ввічливими, висловлюйте повагу. CR треба розглядати як можливість для власного росту та покращення для обох учасників процесу, а не змагання. Тому завжди працюйте з кодом, а не з людиною, яка його написала.

  Нехай propose instead of blame стане вашим керівним принципом у цьому процесі. Тому, якщо критикуєте, завжди пояснюйте, за що та чому, а головне — пропонуйте натомість можливі варіанти покращення.

• Орієнтуйтесь на завдання, яке повинне виконати код. І у ревʼюєра, і в автора коду головне завдання — довести фічу до продакшену, щоб вона якомога швидше почала приносити користь. Тож тримайте це в голові, коли ревʼюїте код, та запитуйте себе, чи запропоновані зміни наближають його до цілі.

• Перевірте код згідно з пірамідою ревʼю. В основі піраміди лежать обовʼязкові характеристики коду, а на її верхівці — ті, що не є обовʼязковими, але допомагають наблизити ваш код до ідеалу. Тож, пройдемо від основи до верхівки піраміди.

Correctness. Іноді розробники взагалі не розуміють, навіщо вони пишуть код і яку проблему він вирішує. Щоб уникнути такої ситуації, можна запитати себе: Чи робить цей код те, що повинен? Чи справляється він з едж-кейсами? Його можна адекватно протестувати? Наскільки правильно і повно його було протестовано? Чи добре він справляється з конкретним юз-кейсом?

Security. Багато хто часто забуває про дотримання безпеки під час написання коду. Щороку ми чуємо новини про великі витоки паролів і особистих даних по всьому світу. Тому як під час написання, так і під час перевірки коду потрібно одразу думати про те, чи є в ньому якісь уразливості, і постаратися запобігти їхньому створенню або вирішити ці питання до релізу.

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

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

Тому код має бути написаний зрозуміло, а це означає, що він:

• відображає те, що написано в бізнес-реквайрементах;
• коректно використовує назву змінних, функцій і класів;
• спирається на загальноприйняті конвенції.

Elegance. Елегантним можна вважати той код, який використовує загальновідомі патерни, є зрозумілим і простим. Запитайте себе, чи було б вам самим цікаво працювати з цим кодом, чи могли б ви ним пишатися. Бо ви як рев’юер теж причетні до створення цього коду. Якщо відповідь позитивна, то код, напевно, можна вважати елегантним.

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

Запитайте себе, чи став код після вашої з ним роботи надихати інших інженерів прагнути до таких самих поліпшень; чи покращила ваша робота документацію коду; чи запропонували ви кращі патерни; чи вирішують ваші зміни якийсь із технічних боргів; чи приносить він ще якісь поліпшення.

Тож якщо в процесі ревʼю ви взяли до уваги всі ці параметри, то ви допомогли значно покращити цей код. Також це означає, що ви самі багато над чим замислились, щоб перевірити його на відповідність цим критеріям, і цей процес був корисним не тільки для автора коду, але й для вас як для ревʼюєра.

Життєвий цикл CR

Ми розглянули, як готувати код до ревʼю і як його проводити, отже, підсумуємо увесь процес. Важливо памʼятати, що код-ревʼю не обмежується лише перевіркою вашого коду іншою людиною. Тож розберемося, які етапи проходить код на ревʼю.

1. Перше (авторське) ревью. Як я вже згадував, перш ніж передавати код далі, перевірте його самі. Це допоможе позбавитись поверхневих помилок.
2. CR демо (опціонально). Не завжди ваш код буде зрозумілим сам по собі. Бувають важливі фічі, які мають велике значення для бізнесу, або буває так, що ви працюєте з якоюсь новою технологією, в якій ви вже розібралися, а інші розробники — ще ні. Для таких випадків CR демо допоможе краще зрозуміти контекст і, відповідно, ваш код.
3. 1-on-1 час ревʼюєра з вашим кодом. Це стандартний процес і основа CR. На цьому етапі ревʼюер, керуючись принципами, які ми щойно розглянули, перевіряє авторський код та надає зворотній звʼязок.
   
4. Відмова або успішне проходження ревʼю. Після ревʼю ваш код може бути або успішно прийнятим, або такимм, що потребує корективів. У разі, якщо ваш код не пройшов рев’ю, тікет переводиться в колонку not started. Через це може зрости час на зворотний зв’язок, оскільки тікету доведеться знову пройти CR. Тому автору потрібно стежити за тікетами, за які він відповідає, і самостійно нагадувати рев’юеру про їхній статус. У разі успіху тікет переміщується далі по борду та наближається до релізу.
   
5. Conflict resolutions. Це конфлікти вашого тікету з іншими на момент інтеграції тощо. Уникнути конфліктних ситуацій допоможе колаборація з іншими розробниками, які теж працюють у цій зоні. Домовтеся, що спочатку зробите пересічні тікети, а потім — усі інші.

Що маємо в кінці

Кожний з нас виступає у ролі автора кода, а також як ревʼюер для своїх колег. Тому однаково важливо якісно та ефективно виконувати свою роботу на обох сторонах цього процесу.

Якщо ставитися до CR не як до необхідної формальності, а як до обміну досвідом і можливості чомусь навчитися, то процес стане набагато ефективнішим та принесе користь усім його учасникам. Тож готуйтеся до CR, поважайте одне одного та завжди памʼятайте про цілі, які переслідує ваш код.

Усім якомога більше апрувів та менше реджектів!