Перевод статьи Габриеля Гузмана “Good Practices — Code Review Comments”.
Если вы делаете ревью кода, то, скорее всего, снова и снова сталкиваетесь с одними и теми же проблемами. Люди, которые впервые вносят что-то в вашу базу кода, могут не знать внутренних стандартов вашей команды. Они могли раньше работать с другим языком и делать все немного иначе. Полезным инструментом для таких случаев является документ “Комментарии просмотров кода” («Code Review Comments»).
«Code Review Comments» это собрание комментариев, которые появляются снова и снова в ходе просмотров кода. Например, если вам постоянно приходится говорить людям “Убедитесь, что вы используете prepared statements, когда отсылаете input на SQL-сервер”, вы можете внести это в документ. Затем, обнаружив unescaped SQL, вы можете не объяснять еще раз, а просто сослаться на документ.
Прием новых разработчиков
Когда в вашу команду приходят новички, вы можете отсылать их к этому документу, чтобы они могли быстро ознакомиться с вашими стандартами. Будет хорошей идеей поместить там такие вещи, как:
- Весь код перед подачей на ревью должен быть приведен к нашим внутренним стандартам в отношении стиля кода (у вас же есть стандарты кода, правда?).
- Код, представленный как PR (pull request), должен быть проверен другим разработчиком до его объединения.
- Мы предпочитаем использовать “guard clauses”, а не глубоко вложенные блоки if/else (см. https://www.thechrisoshow.com/2009/02/16/using-guard-clauses-in-your-ruby-code/).
В этом документе должно быть все, что не покрывается вашим linter/code formatter.
Уменьшение умственной нагрузки
Чтение кода считается более сложным занятием, чем его написание, поэтому хорошо все, что уменьшает умственную нагрузку того, кто выполняет ревью. Если ваш документ с комментариями обзоров кода охватывает все простые вещи, то человек, делающий ревью, может сосредоточиться на сути запроса на внесение изменений, а не на мелочах.
Подобный документ также поможет с разницей в личных стилях, которая может проявиться в ходе ревью. Если четко объявлено, что ваша команда предпочитает короткие имена переменных, то в таком случае кому-то будет сложнее спорить и утверждать, что loopIndexVariable — лучшее имя для индекса цикла, чем i, потому что оно более описательное.
Ограничение bike-shed
Если вы постоянно ловите себя на том, что спорите о неважных вещах, вы можете поместить это в документ (как только команда придет к согласию о лучшем цвете для велосипедного сарая). И когда в следующий раз кто-то подумает, что другой цвет подойдет лучше, вы просто дадите ему ссылку на документ и дело с концом. Больше об «эффекте велосипедного сарая» читайте здесь.
Формализация стандартов команды
Зачастую, чем дольше команда работает вместе, тем больше она разрабатывает неписаных правил о том, каков должен быть код. Это прекрасно работает, пока в команду не приходит новый человек. Новичку приходится постигать эти стандарты путем проб и ошибок, что может вызывать раздражение и отнимать время.
Ведение документа с комментариями обзоров кода может помочь формализовать эти неписаные стандарты и уменьшить трения при появлении нового члена команды. Новичок может просто прочесть этот документ и избежать нескольких случаев, когда его код не пройдет проверку из-за несоответствия внутренним стандартам, о которых знают все, кроме него.
Не перестарайтесь
Что вам точно не нужно в работе с подобным документом, так это перегрузить его мелочами, которые сами станут источником умственной нагрузки для разработчика. Он должен быть предельно сжатым и легким для чтения.
Вот хороший пример таких комментариев в командах Go. В нем содержатся вещи, которые постоянно всплывают в ходе ревью кода. Их добавили в документ для улучшения опыта разработки и обзоров кода как для автора, так и для того, кто делает ревью.
Начните вести свой собственный документ
Начать подобный документ очень просто. Каждый раз, когда вы делаете ревью и вам приходится что-то повторять больше одного раза, добавьте это в документ. Пускай ваша команда делает то же самое. Затем вы сможете время от времени вместе просматривать получившийся документ чтобы решить, что сохранить, а что убрать.
Когда новый участник присоединяется к команде, отсылайте ему этот документ прежде чем он первый раз отправит свой код на проверку. Это позволит новичку убедиться, готов ли его код к ревью.
Заключение
Ведение документа с комментариями обзоров может стать хорошим подспорьем при приеме в команду новых разработчиков, уменьшить умственную нагрузку проверяющих и формализовать неписаные стандарты команды. Вместо обнаружения этих вещей путем проб и ошибок новый участник может просмотреть документ и быстро приспособиться к внутренним стандартам новой команды. Это может уменьшить трения в команде и улучшить опыт прохождения ревью кода для всех участников процесса.
А у вас ведется такой документ? Расскажите в комментариях!
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]