Прегледът на кода понякога може да бъде стресиращ и разочароващ процес. Когато един инженер пише код, той има пълен контрол върху това как е написан техният код, как функционира и как се тества. Прегледът на кода включва включване на други хора в процеса на разработка, за да си сътрудничат; без насоки, което може да доведе до значителна несигурност от страна на разработчика.
Но тази несигурност не е задължително да съществува. Солиден набор от насоки за всеки инженер и рецензент ще стандартизира очакванията за процеса на преглед на кода и ще гарантира, че нашият код ще влезе в основния дори по-бързо, с по-малко разходи и усилия, необходими от всички участващи.
Имайки това предвид, ето няколко насоки за писане и четене на PR, които използваме в нашия екип от уеб разработчици в IFTTT:
A PR is…
Инструмент за насърчаване на сътрудничеството и осигуряване на качествен код в кодовата база. Това е начин да сме сигурни, че всички сме на една страница. Това е вникване в мисловния процес на един инженер, разпространен в екип. Всички сме отговорни за кода, който влиза в уеб приложението; прегледът на кода формализира тази собственост и гарантира, че разбирането може да поддържа тази собственост в целия екип.
Това не е нито гумен печат, нито е инструмент за пазене на врата. Това е механизъм за споделяне на процеса на разработка с други и за допускането им да помогнат. Вашите колеги трябва да могат да следят развитието на дадена функция и да й влияят във всяка точка.
Добър PR е...
Atomic!
Вие прилагате едно единствено нещо. PR трябва да обясни всичко за това как работи това нещо, нищо повече и нищо по-малко.
Накратко!
Като основно правило PR не трябва да надвишава около 500 LoC (с изключение на автоматично генерирания код). Това е, за да се гарантира, че пластирът е лесен за концептуализиране и изграждане на умствен модел на промените. Ако смятате, че вашият PR трябва да бъде по-голям от това, запитайте се какво може да бъде прекъснато и преместено към други PR.
Няколко съвета как да съкратите PR-ите си:
- Създайте структурата на контролера за страница и HTML + CSS + JS на страницата в отделни комити, скрийте страницата зад превключвател, докато е в процес на разработка.
- Ангажирайте JS класове отделно от действителното им използване във всякакви шаблони
- Добавете промени в моделите отделно от промените в контролерите и изгледите.
За да управлявате това, струва си да се запознаете добре с git rebase. Създайте зависими промени за всеки PR и ако нещо се промени в първия, пребазирайте следващите PR на този. Когато изпращате корекции в Github, просто задайте основния клон за всеки пластир след първия към предходния клон.
Подредено!
Уверете се, че сте прегледали своя PR, преди да помолите другите да го прегледат, потърсете правописни грешки, грешки и т.н. За по-големи промени, тествайте на репетиция. Ако вашият PR все още не е напълно готов, не забравяйте да добавите „WIP“ в името на PR, за да укажете, че все още е в процес на работа.
Добре обяснено!
Моля, не забравяйте да включите описание на това, което добавяте или поправяте, структурата на новия код и връзки към всички подходящи билети.
Насочено!
Добавете конкретни рецензенти към PR и, ако е необходимо, изпратете им директно съобщение, за да ги уведомите, че е готово. Ако PR е нещо, което някой от екипа може да се опита да прегледа, публикувайте го в общ канал.
Тествано!
Всички промени в кода на приложението трябва да идват с тестове, било то единица или интеграция. За по-големи или по-крехки промени, уверете се, че сте тествали върху етапен екземпляр. Това до голяма степен е по преценка на рецензента, но когато се съмнявате, тествайте!
Добър преглед е...
Бързо!
Нашият екип трябва да се стреми да предостави обратна връзка възможно най-скоро. PR трябва да се считат за един от най-високите приоритети за един инженер, зад само активните инциденти.
Внимателно!
Опитайте се да оставите всички необходими коментари наведнъж. Отделете време за прегледа, прегледайте го повече от веднъж, опитайте се да следвате потока от данни между методите и класовете.
Комуникативен!
Ако има нещо, което не разбирате, или оставете коментар с молба за обяснение, или се свържете с автора на slack. По същия начин, ако коментар е оставен от рецензент, който авторът не разбира, не се колебайте да поискате разяснение.
Конструктивно!
Всички изграждаме това нещо заедно. PR-ите не са място за показване или териториално отношение към кода. Оставете коментари, които са мили, полезни и градивни.
Гъвкав!
Понякога е трудно да се направи промяна незабавно или поради крайни срокове за продукта, или поради значителни разходи за инж. препроектиране на кода. Добрият преглед трябва да вземе това предвид и да позволи на инженерите да разгледат коментарите по-късно, ако разходите са значителни. Компромисът е ценен.
Всичко по-горе се отнася и за инженер, който отговаря на коментари за преглед.
Моят PR е готов да бъде обединен, когато...
Одобрен е!
Рецензент е разгледал кода и го е одобрил в Github.
Издържа CI!
CI е зелен, а не жълт или червен и тестовете покриват по подходящ начин вашите промени. Ако корекцията не успее да премине и няма очевидни грешки, свързани с вашия код, не се колебайте да задействате отново компилация. Ако обаче отново се провали, потърсете текущи проблеми с инфраструктурата и, ако не успеете, опитайте да видите дали преминава локално и дали вашият код е отговорен за повредата по заобиколен начин.
Уверен съм в промяната!
Ако имате одобрение, корекцията ви преминава CI и все още не се чувствате напълно уверени в промяната, не се колебайте да поискате допълнителни прегледи или напишете още тестове. Не обединявайте код, който не се чувствате сравнително комфортно да обединявате.
Други, полезни ресурси:
„Относно прегледа на кода“ — Глен Д. Санфорд
От бивш мениджър инженер, това парче говори за целия процес на преглед на кода, от културните очаквания за процеса в рамките на екипа, до писането и четенето на рецензии и предлагане на обратна връзка.
„Писане на искания за привличане, които вашите колеги може да се насладят на четене“ — Райън Грийнбърг
Това парче е забавно, бързо четиво от гледна точка на инженер, който пише PR-и, и как да ги напишете, за да бъдат по-лесни за четене.
