Google: How to write code review comments
Google, основываясь на многолетнем опыте, представил свои стандарты того, как лучше всего проводить code review. Все вместе они представляют собой один законченный документ, разбитый на множество отдельных разделов. Это перевод стандартов по проведению Code Review от Google. Вот ссылка на оригинал!
Терминология:
CL — расшифровывается как «список изменений» (“ChangeList”), что означает одно автономное изменение, которое было отправлено в систему управления версиями или подвергается проверке кода. Другие организации часто называют это «изменением» или «патчем».
Как писать комментарии в code review?
- Будьте вежливы
- Объясняйте свои рассуждения
- Соблюдайте баланс между прямыми инструкциями и указаниями на проблемы кода
- Поощряйте разработчиков упрощать код или добавлять комментарии к коду
Вежливость
Важно быть вежливым и уважительным, а также предельно понятным и полезным для разработчика, чей код вы проверяете. Один из способов сделать это — быть уверенным, что вы всегда комментируете код и никогда не комментируете самого разработчика. Не всегда нужно следовать этой практике, но вы должны использовать ее, когда говорите что-то неприятное или спорное. Например:
Плохо: “Почему вы использовали здесь потоки, когда от параллелизма явно не было никакой выгоды?”
Хорошо: “Модель параллелизма здесь добавляет сложность системе без какого-либо реального выигрыша в производительности. Поскольку нет никакого выигрыша в производительности, лучше всего, чтобы этот код был однопоточным”.
Объясняйте ваши доводы
В «хорошем» примере, приведенном выше, можно заметить, что ревьюер помогает разработчику понять причину комментария. Вам не всегда нужно включать эту информацию в комментарии, но иногда полезно дать немного больше объяснений относительно ваших намерений или лучших практик, которых вы придерживаетесь.
Указания
В общем случае, ответственность за исправление CL несет разработчик, а не ревьюер. Вы не обязаны делать детальное проектирование решения или писать код для разработчика.
Однако это не означает, что ревьюер не может чем-то помочь. Вы должны соблюдать надлежащий баланс между указанием проблем и предоставлением непосредственной помощи. Указание на проблемы и предоставление возможности разработчику принять решение часто помогает ему учиться и облегчает анализ кода. Это также может привести к лучшему решению, потому что разработчик ближе к коду, чем ревьюер.
Но иногда более полезны прямые инструкции, предложения или даже код. Основная цель проверки кода — получить наилучший возможный CL. Вторичной целью является повышение квалификации разработчиков, чтобы ревью их CL со временем занимал все меньше и меньше времени.
Просите объяснений
Если вы попросите разработчика объяснить фрагмент кода, который вы не понимаете, это приведет к тому, что он перепишет код более четко. Иногда добавление комментария в код также является подходящим ответом, если только он не объясняет слишком сложный код.
Пояснения, написанные только в инструменте code review, не помогут будущим читателям кода. Они приемлемы только в нескольких случаях, например, когда вы просматриваете область, с которой вы не очень хорошо знакомы, и разработчик объясняет то, что обычные читатели кода и так знают.
