Это вторая часть из двух частей, посвященных обзору кода. Часть первая, Когда ваш код становится нашим кодом, посвящена целям и методам проверки кода. В конце этой статьи есть приложение с полезными ресурсами по обзору кода, используемыми для обеих статей.

Проверка кода - мощный инструмент для создания качественного рабочего кода. Это также может быть источником трений между коллегами. Это мои личные рекомендации, чтобы попытаться уменьшить это трение и сделать проверку кода максимально эффективной. Они не одобрены моей компанией LaunchDarkly, хотя они вызвали мало споров среди моих коллег, когда я представил их внутри компании. Я также уверен, что нарушил все правила в этом списке и, без сомнения, буду продолжать это делать, но тем не менее считаю их полезными.

Рекомендации для обозревателей кода

  1. Будьте конструктивны и конкретны. У вас может быть общая критика, но конкретные предложения дают направление для обсуждения и сокращают время обработки. Если возможно, включите пример кода.
  2. Избегайте повелительного настроения и будьте осторожны со словом «ты» . Старайтесь не говорить «вам следует писать это как…». Поймите, что ваши предложения - это предположения, что они могут быть ошибочными и в конечном итоге не могут быть приняты во внимание по той или иной причине. Также подумайте о том, чтобы использовать «мы» вместо «я», чтобы понять, что вы являетесь частью одной команды.
  3. Обязательно прочтите описание PR полностью. Если вы используете систему продажи билетов - мы используем Clubhouse - также может быть полезно прочитать билет, поэтому в PR-описании должна быть указана такая ссылка. Эта информация, как правило, обеспечивает дополнительный контекст для изменений и избавляет от некоторых вопросов. [N.B. Я по-прежнему считаю полезным для авторов PR повторять информацию о тикете в описании PR, потому что рецензенты могут пропустить этот шаг.]
  4. Будьте доступными. Как равноправный партнер в процессе проверки кода - см. часть первую, вы должны стремиться получить этот код, который вы начали проверять, как можно быстрее.
  5. Не стесняйтесь проводить проверку кода лично. Это иногда называют проверкой кода без дополнительных усилий, и она может значительно сократить время ожидания и путаницу.
  6. Дайте понять, если вы не главный рецензент. Возможно, имеет смысл оставлять комментарии здесь и там, но не оставляйте автора кода в зависимости от того, как вы завершите проверку, если вы считаете, что кто-то другой должен быть основным рецензентом.
  7. Вы делаете этот обзор для своих коллег, а не для автора кода. Ваша ответственность перед автором кода - быть конструктивным, отзывчивым и, возможно, даже помочь автору расти как член команды; ваша основная обязанность - убедиться, что вы и ваши коллеги продолжаете работать с высококачественным и правильным кодом.

Рекомендации для авторов кода

  1. Разбейте изменения на минимально возможные. Сделайте это до проверки. Вы получите более качественные отзывы, и ваши рецензенты будут вам за это благодарны.
  2. Прочтите свой код, прежде чем запрашивать проверку. Вы даже можете сделать это до создания PR, хотя для некоторых рабочих процессов CI может быть полезно создать PR перед проверкой. Мы используем PullReminders для PR-уведомлений и, называя наши PR с префиксом, например WIP, мы можем сказать автоматически добавленным рецензентам (из файлов Github CODEREVIEWERS), чтобы они воздержались перед просмотром PR.
  3. Перед проверкой аннотируйте свой код в Github. Вы можете уменьшить задержку, сохранив некоторое время назад и вперед с рецензентом. Если вы чувствуете необходимость аннотировать строку, вы можете подумать, может ли вам понадобиться комментарий в коде или код можно переписать, чтобы сделать ваше намерение более ясным.
  4. Отвечайте на все отзывы. Если вы этого не сделаете, рецензент может подумать, что вы его пропустили, и почувствует необходимость отреагировать на него.
  5. Не обижайтесь. Мы вместе. Понятно, что вы почувствуете близость к своему коду; вы провели с ним много времени. Сделайте вдох и двигайтесь дальше.
  6. Не спешите с возражением. Постарайтесь понять причину или цель предложения, даже если вы считаете, что конкретное предложение может быть неправильным решением.
  7. Не стесняйтесь предлагать обсудить код лично. Для сложных изменений это может быть намного проще, поскольку это может уменьшить как задержку, так и возможное недопонимание.
  8. Не стесняйтесь предлагать внести изменения в последующий PR. Иногда вам просто нужно внести свои изменения, и это может быть разумным компромиссом.
  9. Прося пояснения, предложите, что, по вашему мнению, может иметь в виду рецензент. Это хороший совет для любого взаимодействия в жизни.
  10. Примите рецензента. Когда этот процесс будет завершен, они будут владеть этим кодом так же, как и вы. Если рецензент предлагает что-то непонятное, вероятно, так оно и есть.

Приложение: другие ресурсы

В Интернете есть множество статей о том, почему ревью кода - это хорошо и как делать это хорошо. Ниже приведены некоторые из них, которые показались мне интересными, даже если я не был с ними на 100% согласен или они не соответствуют нашим собственным неустановленным правилам:

Ряд приведенных выше статей взяты из хорошего списка, опубликованного на github / joho / awesome-code-review.