Полное руководство по код-ревью

19 октября 2022 г.

Ревью кода — это не поле боя, рецензент — не противник автора. Оба они преследуют одни и те же цели — решать проблемы продукта и создавать высококачественную кодовую базу. Давайте копнем глубже и поймем, как сделать незабываемый код-ревью со стороны рецензента.

Не теряйте время

Есть вопросы, которые время от времени повторяются. Сначала в одном пулл-реквесте, потом в другом, один раз от одного автора, потом от другого. Они абсолютно идентичны - это рутина. И, как и положено каждой рутине, она должна быть автоматизирована, и действительно, если что-то можно автоматизировать, то это нужно автоматизировать.

Стиль кода. Нет смысла спорить и спорить о стилях кода, которые на 100 % уже были определены много-много раз и десятилетий назад всеми участниками проекта или всем сообществом. Установите длину строк, имена методов и классов в линтере и форматере и забудьте об этом.

Тесты. Автоматизируйте все тесты (модульные, интеграционные, сквозные), их запуск, покрытие и другие вещи. Просто настройте их, и установите приемлемый порог для метрик, например, охват нового кода в PR должен быть не менее 90% и эта простая настройка облегчает жизнь многим людям.

Не повторяйтесь (DRY). Часто повторяющиеся элементы следует собирать в одном месте, чтобы их можно было легко централизованно изменить или исправить. Собирайте процент дублирования кода во всех приложениях и обрабатывайте его так же, как тесты.

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

n Резюме. Инженеры должны сосредоточиться на решении проблем, а не на повторении рутины. То, что я мог бы гарантировать, настроить хотя бы базовую автоматизацию любых тем выше и среднее качество код-ревью резко увеличилось бы. Это сэкономит время рецензентам, потому что им нужно проверять код, если:

• Не все тесты проходят
• Недостаточное тестовое покрытие/процент ниже допустимого
• Процент дублирования кода выше допустимого
• Код "запахи"
• Неожиданная точка доступа

Общие правила

Уважение. Будьте вежливы и уважайте автора. Помните, что участники проверки кода здесь, чтобы помогать друг другу и разделять одни и те же цели. Можно критиковать код и никогда человека.

Задача. Не проводите проверку кода, пока полностью не поймете, что было решено. Получите информацию о том, в чем была проблема, реальные случаи, условия, шаги для воспроизведения, аудиторию функции и т. д. Попросите демонстрации кода, сеансы проверки кода или даже просто встречи по синхронизации, чтобы прояснить все аспекты данной задачи.

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

Просмотр

Ниже я собрал некоторые основные категории и вопросы, на которые действительно стоит обратить внимание, в порядке их приоритета от наиболее важных.

Бизнес-цели

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

Реализация

На следующем уровне начните обращать внимание на цифры, показатели и отчеты. Анализируйте код с разных сторон.

n Безопасность. Создает ли это уязвимости или устраняет их? Насколько стабильным он будет под атакой? Пассивный или активный? Некоторые специфические, такие как DDoS или любые виды инъекций (SQL, межсайтовые скрипты и т. д.)?

Обработка ошибок. Как осуществляется правильная обработка ошибок? Может ли приложение сломаться или отправить отчет в программу отслеживания ошибок? Будет ли он показывать все трассировки стека конечному пользователю? Это повторяемое неудачное действие? Будут ли данные повреждены или возникнут коллизии?

Производительность. Повлияли ли новые изменения на производительность? Возможность утечки памяти, вызванная этим кодом? Насколько хороша оптимизация? Все ли сделано для того, чтобы этот код назывался эффективным (системы кэширования, пулинг ресурсов, сжатие данных и т.д.)

Интеграция. Как это будет работать с другими модулями и системами? Повышает ли это связность кода? Можно ли его легко заменить другими реализациями или интеграцией? Насколько совместим код с другими версиями других частей системы (например, обратная совместимость нового выпуска)?

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

Просмотр этой категории и ответы на эти вопросы должны подтвердить правильный выбор инструментов для реализации.

Удобство сопровождения

Здесь одним из главных вопросов будет — «а как бы код жил без автора?» будет ли автор легендарным или проклятым.

Читаемость. Код — это буквы, из которых складываются слова, слова, из которых строятся линии, и т. д. И весь код звучит как классическая книга, но написан на определенном языке, языке программирования. Таким образом, читабельность следует понимать буквально, код должен строить историю (например, класс, функцию) с хорошо написанными символами (например, аргументами, переменными и т. д.), и они должны выполнять действия (вызывать другие функции, изменяться или быть неизменяемыми и т. д.). Насколько читабелен код? Мог ли он поддерживаться кем-либо, кроме автора? Разборчивость именованных аргументов, переменных, функций и т. д.

Документация. Экономит много времени при разработке, сокращает время на синхронизацию, упрощает процесс адаптации и в целом хорошее хранилище для базы знаний о проекте. Насколько хорошо документирован код? Остаются вопросы после прочтения? Все ли необходимые файлы MD и внешняя документация добавляются/обновляются в соответствии с изменениями?

Повторное использование. Чтобы предотвратить дублирование кода, когда логика может быть общей для более чем одного модуля, ее можно переместить в общие места, такие как помощники, утилиты и т. д. Можно ли повторно использовать некоторые части кода где-то еще? Если нет, то оправдана ли его уникальность? Если да, то не было ли оно слишком сложным для достижения этого показателя?

Дизайн. Код никогда не должен заново изобретать велосипед. Существуют десятки уже принятых сообществом лучших практик и определенных шаблонов проектирования. Решения распространенных проблем в программной инженерии. Использует ли код лучшие практики и шаблоны? Правильно ли он используется?

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

Заключение

Провести качественную проверку кода — это большой труд. Reviewer — это самые первые ворота технического качества для него. До слияния код принадлежит и управляется его автором, но после этого ответственность будет передана всей команде. Именно поэтому рецензенты должны быть заинтересованы в передаче стабильного, надежного и безупречного состояния кода. Обзор кода — это возможность для роста. Рост как для рецензента, так и для автора.

---

Оригинал