7. Будьте скромным и позитивным
Мы все видели эти обзоры кода, когда код продолжает двигаться вперед и назад, и требуется несколько итераций, пока он, наконец, не будет объединен.
Не только автора раздражает, что рецензент не примет код, но и рецензента, который будет думать, что автор просто «не понял».
Однако есть и хорошие новости; не только от автора изменений зависит, чтобы обратная связь была получена гладко и процесс пошел быстрее. Есть также несколько хороших практик, которые рецензент может использовать, чтобы сделать процесс рецензирования менее скучным и более ясным.
Эффективные проверки кода — это выигрыш для всех, потому что:
- Автор будет более четко понимать ваши отзывы, что приведет к меньшему количеству итераций изменений кода.
- Вы будете давать автору советы и замечания, которые повлияют на его подход к кодовой базе в целом, чтобы в следующем было меньше «ошибок».
- Работа будет объединяться быстрее, разблокируя потенциальных других.
- По крайней мере, у вас будет качественная дискуссия о выборе реализации.
Обратите внимание, что в этой статье не объясняется, как проводить проверку кода или на что при этом обращать внимание. Вместо этого мы приводим здесь несколько советов и практических правил для вашего подхода и поведения в отношении процесса проверки. Поэтому, если вы уже регулярно просматриваете код в своей работе, эта статья призвана помочь вам пересмотреть некоторые из ваших практик и стать лучшим рецензентом.
Приступим к делу.
1. Всегда говори почему
Давайте посмотрим на некоторые возможные комментарии к обзору:
bad function name
this shouldn't be here
I think this might break
В этих комментариях есть некоторые ошибки, но самая заметная проблема заключается в том, что они не аргументированы. По этим комментариям автор кода может только предполагать, что не так с его кодом, а мы все знаем, насколько предположения плохи — особенно в этом случае;
- Автор может прийти к неправильному выводу о том, почему их название/код неверны, и внедрить неправильное исправление. Это, безусловно, приведет к дополнительной итерации обзора.
- Автор не получит обоснованной обратной связи о том, почему его название/код неверны. В противном случае они, возможно, узнали бы что-то, чего не знали, или расширили бы свой кругозор, увидев то, чего не видели сразу.
Каким может быть лучший комментарий? Давайте проверим пример:
This function name isn't ideal; it should start with a verb to indicate action, and in this case have an indication of the argument, maybe with something like '...ByUserId'. Remember to check our code style docs for more details on this
Да, вы только что написали еще кучу слов, но теперь вы ясно объяснили автору, что не так с их именем и как им следует поступать, когда они думают об именах функций.
Знаете ли вы, как здорово вы почувствуете себя в следующий раз, когда тот же автор пришлет вам обзор кода, и вы увидите, что он/она теперь следовал правильным правилам для имени функции? Попробуйте!
2. Будьте тщательны
Автором кода может быть самый высокопоставленный человек в вашей команде, знающий все тонкости кодовой базы, или новичок, который отправляет свой первый код-ревью.
Это не должно влиять на качество или тщательность вашей проверки кода, и вы не должны давать старшему сотруднику поблажки только потому, что доверяете его работе.
Обзоры кода — это не только обеспечение качества и структуры кода, но и поиск краеугольных камней или ошибок, которые автор мог не заметить, или даже просто случайных опечаток.
И признайтесь, это случается с лучшими из нас. Выявление ошибки до того, как она будет отправлена в производство (и даже на стадии постановки), всегда более эффективна, чем обнаружение ошибки, сообщение о ней, поиск причины, исправление проблемы и отправка ее на повторную проверку кода.
3. Не давайте полный результат
Поскольку рецензент кода меняется, вы не должны исправлять код или придумывать решение, когда вы обнаружите проблему.
Да, вы можете (а иногда и должны) помочь или обсудить свои идеи, но это не значит, что вы должны давать полное решение проблемы. Рассмотрим комментарий, подобный следующему:
this method doesn't quite do the job, it should be something like: ``` <code here> ```
Когда вы сделаете это, разработчик кода мало что извлечет из вашего предложения; в некоторых случаях они даже скопируют и вставят ваше решение и просмотрят его, не задумываясь о нем подробно.
И особенно, если вы постоянно делаете это, разработчик легко обленится и не будет слишком много учитывать при написании сложного кода, думая, что рецензент предложит исправление, если обнаружит, что в нем что-то не так. . Если вы делаете это регулярно, не удивляйтесь, если вас часто выбирают в качестве рецензента изменений кода в вашей команде.
В этом случае правильным поведением будет описание того, как должен выглядеть метод. Вы должны указать, почему это не работает, и как бы вы подошли к решению проблемы, возможно, запишите это шаг за шагом. В некоторых случаях даже некоторый псевдокод допустим. Пока вы заставляете разработчика действительно думать о предложенном вами подходе, а не просто копировать и вставлять свое решение, вы хороши.
4. Не откладывайте обзор
В любой команде, но особенно в командах инженеров, очень важно не блокировать работу друг друга.
Переключение контекста — непростая задача для разработчика. И в ожидании обзора кода по одной из своих проблем им придется переключиться на другую историю, чтобы работать над ней, и переходить туда и обратно, пока они получают обзор и отвечают на его комментарии.
Это в любом случае произойдет, даже если проверка произойдет очень быстро — потому что разработчик захочет перейти к следующей задаче. Однако, чем дольше затянется обзор, тем больше историй и обзоров кода разработчику придется обрабатывать таким образом, переходя туда и обратно между ветками, перечитывая свой код (опять же, переключение контекста), разрешая конфликты слияния и т. д. .
Кроме того, представьте, что вы фактически блокируете работу человека; это означает, что они не могут продолжать свою работу, пока эта функция не будет завершена / изменения кода не будут объединены. В этом случае они буквально не смогут работать, пока вы не закончите проверку. Все это неэффективно и раздражает обе стороны (потому что, да ладно, разработчик, вероятно, будет отправлять рецензенту сообщения каждые 30 минут с просьбой о его / ее обзоре, как только они будут заблокированы 🙃).
Чтобы убедиться, что вы не уступаете место такому хаосу, всегда полезно отдавать приоритет проверкам кода в своем расписании. Конечно, у вас могут быть более срочные задачи, над которыми нужно работать, или вы не всегда можете сразу выделить время для работы над обзором, но вы обязаны найти правильный баланс между собственной работой и обзорами.
Если вы несете ответственность за проверку кода для большого количества людей, выделяйте в своем расписании каждый день временной интервал для проверки кода и сосредоточьтесь только на них в течение этого времени (или, может быть, два интервала для более быстрой обработки нескольких итераций).
5. Следуйте рекомендациям
Если ваша команда достаточно большая или структурированная, у вас, вероятно, есть некоторые рекомендации, написанные в базе знаний, объясняющие рекомендации по написанию кода для проекта/базы кода.
Он может включать общие подходы к организации кода, соглашения об именах и множество вариантов дизайна. Если вы активно пишете код и просматриваете код других, вы, вероятно, привыкли к этим рекомендациям.
Но вы должны попытаться вернуться к рекомендациям и быстро перечитывать их каждые пару недель или каждый месяц. Вы будете удивлены, увидев, сколько моментов вы забыли или на которые не обращали внимания в обзорах кода.
Если у вашей команды нет таких руководств, вероятно, было бы неплохо написать их во время проверки кода. Всего за пару обзоров кода вы наверняка составите длинный список моментов, на которые вы обратили внимание во время обзора.
Что еще более важно, такой список руководств будет служить единственным источником правды в вашей команде, гарантируя, что у всех авторов кода и рецензентов есть ресурс, на который можно обратить внимание при написании/обновлении/чтении кода.
6. Хвалите хороший код
Проверка кода не всегда связана с плохими новостями. Иногда вы будете натыкаться на код, который заставит вас оценить автора; кусок логики, очень эффективная оптимизация запросов или блестящий UX. Скажи это.
Вы можете прокомментировать связанный код просто с помощью nice! или более длинным предложением, указав, что вам в нем понравилось. В любом случае человек почувствует, что его оценивают, и это определенно влияет на командную работу. Кроме того, если остальная часть кода не так хороша, они не оставят плохого настроения после проверки.
Вдобавок ко всему, теперь автор подтвердит, что написанная им статья на самом деле хороша, поэтому он может попытаться создать больше подобного контента в будущем или выполнить аналогичные действия для решения других проблем.
7. Будьте скромны и позитивны
За прошедшие годы я наткнулся на множество отзывов, в которых было написано this is stupid или просто no. Я мог бы написать некоторые из них тоже в некоторые плохие дни.
Не говоря уже о вышеупомянутых пунктах с указанием причины и т. Д., Такие комментарии просто оскорбительны и обескураживают и не создают никакой ценности. Gitlab дает несколько хороших советов по этому поводу, если вы хотите прочитать дальше, и это звучит очень в соответствии с ценностью их компании позитивное намерение.
Короче говоря, полезно быть добрым в комментариях к обзору, уважать время и труд другого человека и предполагать, что он старался изо всех сил при написании кода. Нет абсолютно никакой пользы в хвастовстве, унижении или гневе в код-ревью.
Давайте посмотрим на некоторые примеры из реальной жизни, которые я скопировал из предыдущих обзоров кода. Обратите внимание на слова, которые задают тон в предложениях.
- shouldn’t this be taking "value" as well 🤔 - maybe you can use "find"instead - I think start the name with "get..." - "Synchronize"sounds weird here imho. - please add an empty line here
Поверьте, немного imho или «🤔» будет иметь большое значение.
8. Укажите на ресурсы
Я не могу сказать вам, сколько раз мы делились этой ссылкой о заказе свойств css друг с другом в обзорах кода в мои первые дни работы с фронтендом (наверное, нужно было просто настроить stylelint 🙈). Кажется, это было даже в моих закладках в какой-то момент.
Если есть известный вам ресурс, который поможет автору кода решить проблему, дайте ссылку на него в своем комментарии. Чаще всего они оценят комментарий, и он может даже стать для них ресурсом, который они будут регулярно использовать в своей работе. Этот ресурс также может быть отдельным разделом руководств вашей компании, если он большой и информацию трудно обнаружить.
Возможно, еще более важный ресурс, на который вы можете указать, находится в кодовой базе, над которой работает автор. Подобная логика или компонент, который уже был реализован кем-то другим в прошлом, может стать отличным руководством для автора, и он может не знать об этом конкретном разделе кодовой базы, если не работал с ним раньше.
Если вы обнаружите код, который нужно улучшить, и знаете, что подобный фрагмент был написан ранее, не думайте, что автор знал, что его можно найти. Укажите это в своем комментарии, чтобы автор мог сравнить свой код с существующим, внести улучшения или следовать тем же правилам, когда это необходимо.
9. Это не ты, это они
При чтении кода для проверки важно, чтобы вы могли легко его понять. Если какая-то часть кода кажется вам тарабарщиной, это не значит, что вы виноваты в том, что недостаточно внимательно прочитали код. Наоборот, это означает, что код просто недостаточно ясен.
Если у вас есть проблемы с пониманием того, что делает этот фрагмент, другим разработчикам, вероятно, будет трудно понять это в будущем, когда им понадобится коснуться этой части кода. Когда вы обнаружите такой код, вам не следует стесняться говорить об этом. И не просите автора объяснить вам этот фрагмент кода, вместо этого попросите его переписать переписать.
Если действительно нельзя написать более понятно, то хотя бы попросите автора добавить комментарии в код. Не стесняйтесь задавать вопросы, чтобы понять цель кода, чтобы вы могли предложить альтернативные подходы и обсудить решения, но вы не должны довольствоваться только ответом, и вы должны убедиться, что код, который в конечном итоге объединяется, легко понятен.
10. Твое не всегда правильно
Обычно существует более одного способа добиться цели. Читая фрагмент кода, вы, вероятно, представите себе другие способы сделать это и почувствуете склонность предлагать его в комментарии, потому что это лучшее решение. Иногда нужно спросить себя: действительно ли это лучшее решение? Или способ автора тоже хорош, но предложение ближе к тому, как вы всегда это делаете?
Если нет явного преимущества в сложности или удобочитаемости кода, подумайте дважды, прежде чем предлагать переписать его. Перечитайте код и убедитесь, что он соответствует принятым в вашей команде соглашениям и стилям кода, что он хорошо выполняет свою работу, и сравните его с альтернативным вариантом, чтобы увидеть, как он повлияет на качество кода. Если способ автора приемлем, но вы по-прежнему считаете, что ваш вариант лучше, напишите его как предложение, а не как обязательное изменение, и будьте открыты для обсуждения с автором причин и деталей изменения, которое вы предлагаете.
Надеюсь, эти советы помогут вам стать более эффективным рецензентом кода и в конечном итоге сэкономят время вам, автору кода и команде в целом. Дайте мне знать в комментариях, если у вас есть какие-либо мысли по поводу вышеизложенного или любые другие предложения, которые могут пригодиться при просмотре кода.
