Код-ревью — полезный инструмент для командной разработки и для прокачки собственных навыков. Код-ревью помогает обнаружить недочёты в коде: как синтаксические или стилистические ошибки, так и неоптимальные или неэффективные подходы. В командной разработке, когда команда делает большой проект, код-ревью также помогает оставаться в курсе изменений в разных частях кода.
Когда программист-новичок впервые сталкивается с код-ревью, он часто расстраивается. В его коде по неопытности часто оказывается довольно много проблем, которые видит более опытный разработчик. Однако очень важно уметь правильно принимать обратную связь, ведь задача ревьюера такая же, как и задача разработчика — сделать код проекта наиболее качественным и эффективным.
Меня зовут Артём Коломацкий, я старший ревьюер бэкенд-факультета в Яндекс.Практикуме. Я расскажу про практики, которые мы используем в код-ревью наших студентов. Часть из них — наши внутренние правила, а часть — универсальные советы, которые вы легко сможете применить у себя в команде.
В Практикуме мы проводим ревью кода на собственной онлайн-платформе, которая называется «Ревизор». Туда попадают все сданные студентами работы. Платформа работает по аналогии с интерфейсами в Gitlab/Github/Bitbucket: можно просмотреть список файлов, изменения между версиями, а также оставить комментарии к определённым строкам.
Кроме того, код студента можно скачать, чтобы запустить и проверить на локальной машине, а также при желании оставить комментарии непосредственно внутри файлов, чтобы потом импортировать их обратно на платформу. Это сделано для тех, кому удобнее смотреть код в собственном редакторе или IDE.
Так выглядит страница, на которую попадает ревьюер, когда начинает проверять работу. Тут мы видим вкладку «Задание» — в ней приведён текст задания. Папки и файлы студента можно увидеть и прокомментировать на вкладке «Код-ревью», а во вкладке «История» посмотреть предыдущие варианты этой работы студента.
Во вкладке «Код-ревью» можно оставлять разные типы комментариев к коду.
Ну а в последней вкладке видно все предыдущие варианты с комментариями.
Интерфейс у студента очень похож на интерфейс ревьюера: видно комментарии к файлам и общий комментарий. Также есть возможность оставить отзыв на работу ревьюера. Всю обратную связь мы внимательно обрабатываем и разбираем вместе с ревьюерами.
Главное отличие «Ревизора» от других платформ в том, что у нас комментарии делятся на три типа: «Надо исправить», «Отлично» и «Можно лучше».
Что значат эти типы комментариев? «Надо исправить» — это обязательные правки. К ним относятся несоответствия заданию, грубые стилистические ошибки, неверное использование тех или иных инструментов и подходов.
«Можно лучше» — это о небольших помарках, а также о том, что не даётся в теории курса. Важный момент в том, что мы не требуем от студентов сразу писать идеальный код, мы двигаемся к этому постепенно с течением курса, поэтому наши ревьюеры знают, что покрыто теорией, а что нет, и могут дать дополнительную информацию или новые материалы для ознакомления в процессе ревью или при личном общении.
«Отлично» — это комментарии, которыми мы хвалим студентов за то, что они верно справились с заданием или использовали нестандартные и интересные подходы.
В Практикуме студенты учатся по спринтам. Спринт длится две недели, и за это время студент изучает законченную часть теории, например ООП в Python. По завершении спринта студенты пишут итоговый проект. Он небольшой, но позволяет студенту закрепить материал, а ревьюеру — убедиться в том, что студент усвоил теорию как следует.
Например, в случае спринта по ООП итоговый проект — это калькулятор валют. Так как в начале пути программиста очень важно привить культуру «красивого кода», мы особенно внимательно относимся к стилистическим ошибкам — соблюдению стайлгайда и повышению читаемости кода. Помимо этого мы следим за эффективностью и оптимальностью решения, например, что функция не потребляет лишней памяти или не делает запросов в базу, которых можно было бы избежать.
Как и в ревью на рабочем проекте, мы проверяем, что были выполнены поставленные требования, но если в случае продакшн-разработки это задача, поставленная менеджером, то у нас на курсе это задание итогового проекта спринта.
По нашим правилам один раз за отправку проекта на ревью студент может обращаться к ревьюеру с вопросами. Обычно таких отправок за проект получается от трёх до пяти штук. Так мы учим студентов правильно подходить к вопросам: прежде чем что-то спросить, нужно обработать проблему самостоятельно, разобраться в ней, подготовить вопрос и уже потом обратиться к ревьюеру. Вопросы к ревьюеру должны касаться только самих правок, например, если студент не понял, что именно требует ревьюер.
Если студент не понимает, как исправлять ошибку, он может обратиться к наставнику. Они занимаются помощью с решением финальных проектов и прохождением остальной теоретической части курса. Бывают ситуации, когда студент считает, что ревьюер не прав или что правка, которую он требует, — некритичная. Поэтому обязательное требование к ревьюеру — уметь грамотно объяснить необходимость того или иного исправления.
Постепенно мы пришли к внутренней формуле «идеального комментария».
Вот пример комментария:
А вот пример комментария «Отлично» за выбор эффективного решения:
Или пример необязательной правки:
Вот так выглядит хороший абстрактный комментарий, написанный по такой формуле:
Но бывают случаи, когда студент и ревьюер всё равно не могут договориться. В продакшн-разработке тоже случаются такие случаи. Там принято обсудить проблему в комментариях к пулл-реквесту, затем обсудить её в личной переписке и, если не удается достичь консенсуса, привлечь старшего коллегу. Для ревьюеров «старший коллега» — это старший ревьюер, человек, который управляет всеми процессами, которые касаются ревью на факультете. В случаях недопонимания между ревьюером и студентом он включается в диалог и разрешает конфликт.
Первый и самый главный принцип: когда работа попадает к ревьюеру на проверку, он должен проверить её за сутки. Это важно, потому что процесс ревью блокирует дальнейшее обучение студента — без сдачи итогового проекта нельзя двигаться дальше по курсу.
Если работа кажется идеальной и хочется сразу её принять, нужно очень внимательно проверить её ещё раз — мы всегда стараемся предложить улучшения кода сверх программы курса и посоветовать что-то новое. Это помогает студентам получить больше полезной развивающей обратной связи.
Мы стараемся сохранять индивидуальность каждого ревьюера — не грести всех под одну гребёнку и давать простор для самореализации. Мы не хотим превращать ревьюеров в роботов, а хотим, чтобы студенты чувствовали, что их ревьюит живой человек, поэтому у нас нет шаблонных комментариев.
По схожей причине мы закрепляем студентов за одним ревьюером на весь срок обучения. Это нужно, чтобы студент и ревьюер привыкли к друг другу, открылись, ведь живой диалог позволяет генерировать более продуктивный фидбек. А ещё чтобы избавить студентов от стресса, ведь программирование — очень субъективная вещь, у каждого ревьюера свой бэкграунд, и некоторые подходы могут различаться.
Перед сдачей первого итогового проекта мы немного раскрываем студентам наши принципы код-ревью: учим их настраивать линтер (утилиту, которая проверяет код на стилистические ошибки) и рассказываем об общих требованиях к коду, на которые мы сами ориентируемся при проверке.
Мы стараемся переключать фокус внимания ревьюеров с незначительных ошибок на более крупные, для этого у нас есть так называемые чеклисты. Чеклисты — это текстовые описания возможных частых ошибок, которые допускают студенты в определённых проектах, с пояснениями, какие из них считать обязательными к исправлению, какие — нет, и где нужно дать студентам дополнительные материалы.
Кроме чеклистов у ревьюеров есть готовые решения проектов от старшего ревьюера — они написаны от лица среднего студента, который будет сдавать проект. В них нет лишнего неизвестного для студента функционала, а также присутствуют дополнительные комментарии для ревьюеров. Вдобавок к каждому проекту авторами написаны автотесты, которые проверяют основной функционал задания.
Недавно в пайплайн тестов, которые прогоняются на платформе при сдаче студентом работы, был добавлен линтер — теперь студентам недостаточно прогнать его локально. Пока все тесты на платформе не пройдут, работа не попадёт к ревьюеру.
За счёт всех этих факторов у ревьюеров появляется больше времени на более качественный фидбек студенту.
По фидбеку ревьюеров и студентов команда авторов регулярно обновляет контент курса: добавляются новые материалы, изменяются задания, а также дополняются тесты, проверяющие работы студентов.
Для тех, кто хочет повысить качество своего кода, я могу посоветовать книги Стива Макконнелла «Совершенный код» и Антона Спрола «Думай как программист».
Когда программист-новичок впервые сталкивается с код-ревью, он часто расстраивается. В его коде по неопытности часто оказывается довольно много проблем, которые видит более опытный разработчик. Однако очень важно уметь правильно принимать обратную связь, ведь задача ревьюера такая же, как и задача разработчика — сделать код проекта наиболее качественным и эффективным.
Меня зовут Артём Коломацкий, я старший ревьюер бэкенд-факультета в Яндекс.Практикуме. Я расскажу про практики, которые мы используем в код-ревью наших студентов. Часть из них — наши внутренние правила, а часть — универсальные советы, которые вы легко сможете применить у себя в команде.
Код-ревью в Практикуме
В Практикуме мы проводим ревью кода на собственной онлайн-платформе, которая называется «Ревизор». Туда попадают все сданные студентами работы. Платформа работает по аналогии с интерфейсами в Gitlab/Github/Bitbucket: можно просмотреть список файлов, изменения между версиями, а также оставить комментарии к определённым строкам.
Кроме того, код студента можно скачать, чтобы запустить и проверить на локальной машине, а также при желании оставить комментарии непосредственно внутри файлов, чтобы потом импортировать их обратно на платформу. Это сделано для тех, кому удобнее смотреть код в собственном редакторе или IDE.
Так выглядит страница, на которую попадает ревьюер, когда начинает проверять работу. Тут мы видим вкладку «Задание» — в ней приведён текст задания. Папки и файлы студента можно увидеть и прокомментировать на вкладке «Код-ревью», а во вкладке «История» посмотреть предыдущие варианты этой работы студента.
Во вкладке «Код-ревью» можно оставлять разные типы комментариев к коду.
Ну а в последней вкладке видно все предыдущие варианты с комментариями.
Интерфейс у студента очень похож на интерфейс ревьюера: видно комментарии к файлам и общий комментарий. Также есть возможность оставить отзыв на работу ревьюера. Всю обратную связь мы внимательно обрабатываем и разбираем вместе с ревьюерами.
Главное отличие «Ревизора» от других платформ в том, что у нас комментарии делятся на три типа: «Надо исправить», «Отлично» и «Можно лучше».
Что значат эти типы комментариев? «Надо исправить» — это обязательные правки. К ним относятся несоответствия заданию, грубые стилистические ошибки, неверное использование тех или иных инструментов и подходов.
«Можно лучше» — это о небольших помарках, а также о том, что не даётся в теории курса. Важный момент в том, что мы не требуем от студентов сразу писать идеальный код, мы двигаемся к этому постепенно с течением курса, поэтому наши ревьюеры знают, что покрыто теорией, а что нет, и могут дать дополнительную информацию или новые материалы для ознакомления в процессе ревью или при личном общении.
«Отлично» — это комментарии, которыми мы хвалим студентов за то, что они верно справились с заданием или использовали нестандартные и интересные подходы.
В Практикуме студенты учатся по спринтам. Спринт длится две недели, и за это время студент изучает законченную часть теории, например ООП в Python. По завершении спринта студенты пишут итоговый проект. Он небольшой, но позволяет студенту закрепить материал, а ревьюеру — убедиться в том, что студент усвоил теорию как следует.
Например, в случае спринта по ООП итоговый проект — это калькулятор валют. Так как в начале пути программиста очень важно привить культуру «красивого кода», мы особенно внимательно относимся к стилистическим ошибкам — соблюдению стайлгайда и повышению читаемости кода. Помимо этого мы следим за эффективностью и оптимальностью решения, например, что функция не потребляет лишней памяти или не делает запросов в базу, которых можно было бы избежать.
Как и в ревью на рабочем проекте, мы проверяем, что были выполнены поставленные требования, но если в случае продакшн-разработки это задача, поставленная менеджером, то у нас на курсе это задание итогового проекта спринта.
По нашим правилам один раз за отправку проекта на ревью студент может обращаться к ревьюеру с вопросами. Обычно таких отправок за проект получается от трёх до пяти штук. Так мы учим студентов правильно подходить к вопросам: прежде чем что-то спросить, нужно обработать проблему самостоятельно, разобраться в ней, подготовить вопрос и уже потом обратиться к ревьюеру. Вопросы к ревьюеру должны касаться только самих правок, например, если студент не понял, что именно требует ревьюер.
Если студент не понимает, как исправлять ошибку, он может обратиться к наставнику. Они занимаются помощью с решением финальных проектов и прохождением остальной теоретической части курса. Бывают ситуации, когда студент считает, что ревьюер не прав или что правка, которую он требует, — некритичная. Поэтому обязательное требование к ревьюеру — уметь грамотно объяснить необходимость того или иного исправления.
Формула идеального комментария
Постепенно мы пришли к внутренней формуле «идеального комментария».
Идеальный комментарий содержит:
- ссылки на дополнительные материалы и/или документацию;
- развёрнутые объяснения;
- пояснение необходимости выбора иного решения;
- мягкие формулировки («лучше» вместо «нужно» и вместо повелительного наклонения «сделай так»);
- альтернативные примеры кода — такого, который студент не сможет бездумно скопировать и сдать, в нём придется разобраться и отредактировать;
- наводки на решение. Лучше не давать готовое решение, а дать студенту возможность дойти до него самостоятельно.
Вот пример комментария:
А вот пример комментария «Отлично» за выбор эффективного решения:
Или пример необязательной правки:
Вот так выглядит хороший абстрактный комментарий, написанный по такой формуле:
Здесь лучше использовать кое-что другое, что реализует такой-то функционал, потому что вот это работает медленнее. Пример кода. Ссылка на бенчмарк, ссылка на пояснение «этого».Эта формула позволяет вынести максимум пользы из ревью. Мы помогаем студенту найти правильную идею для реализации исправления, при этом он понимает, зачем нужна эта правка.
Но бывают случаи, когда студент и ревьюер всё равно не могут договориться. В продакшн-разработке тоже случаются такие случаи. Там принято обсудить проблему в комментариях к пулл-реквесту, затем обсудить её в личной переписке и, если не удается достичь консенсуса, привлечь старшего коллегу. Для ревьюеров «старший коллега» — это старший ревьюер, человек, который управляет всеми процессами, которые касаются ревью на факультете. В случаях недопонимания между ревьюером и студентом он включается в диалог и разрешает конфликт.
Принципы код-ревью
Первый и самый главный принцип: когда работа попадает к ревьюеру на проверку, он должен проверить её за сутки. Это важно, потому что процесс ревью блокирует дальнейшее обучение студента — без сдачи итогового проекта нельзя двигаться дальше по курсу.
Если работа кажется идеальной и хочется сразу её принять, нужно очень внимательно проверить её ещё раз — мы всегда стараемся предложить улучшения кода сверх программы курса и посоветовать что-то новое. Это помогает студентам получить больше полезной развивающей обратной связи.
Мы стараемся сохранять индивидуальность каждого ревьюера — не грести всех под одну гребёнку и давать простор для самореализации. Мы не хотим превращать ревьюеров в роботов, а хотим, чтобы студенты чувствовали, что их ревьюит живой человек, поэтому у нас нет шаблонных комментариев.
По схожей причине мы закрепляем студентов за одним ревьюером на весь срок обучения. Это нужно, чтобы студент и ревьюер привыкли к друг другу, открылись, ведь живой диалог позволяет генерировать более продуктивный фидбек. А ещё чтобы избавить студентов от стресса, ведь программирование — очень субъективная вещь, у каждого ревьюера свой бэкграунд, и некоторые подходы могут различаться.
Перед сдачей первого итогового проекта мы немного раскрываем студентам наши принципы код-ревью: учим их настраивать линтер (утилиту, которая проверяет код на стилистические ошибки) и рассказываем об общих требованиях к коду, на которые мы сами ориентируемся при проверке.
Мы стараемся переключать фокус внимания ревьюеров с незначительных ошибок на более крупные, для этого у нас есть так называемые чеклисты. Чеклисты — это текстовые описания возможных частых ошибок, которые допускают студенты в определённых проектах, с пояснениями, какие из них считать обязательными к исправлению, какие — нет, и где нужно дать студентам дополнительные материалы.
Кроме чеклистов у ревьюеров есть готовые решения проектов от старшего ревьюера — они написаны от лица среднего студента, который будет сдавать проект. В них нет лишнего неизвестного для студента функционала, а также присутствуют дополнительные комментарии для ревьюеров. Вдобавок к каждому проекту авторами написаны автотесты, которые проверяют основной функционал задания.
Недавно в пайплайн тестов, которые прогоняются на платформе при сдаче студентом работы, был добавлен линтер — теперь студентам недостаточно прогнать его локально. Пока все тесты на платформе не пройдут, работа не попадёт к ревьюеру.
За счёт всех этих факторов у ревьюеров появляется больше времени на более качественный фидбек студенту.
По фидбеку ревьюеров и студентов команда авторов регулярно обновляет контент курса: добавляются новые материалы, изменяются задания, а также дополняются тесты, проверяющие работы студентов.
Что почитать
Для тех, кто хочет повысить качество своего кода, я могу посоветовать книги Стива Макконнелла «Совершенный код» и Антона Спрола «Думай как программист».
Как сделать код-ревью быстрее и эффективнее
- Используйте мягкие формулировки и чёткие пояснения в комментариях.
- Комментарии должны быть подкреплены ссылками на дополнительные материалы и/или документацию.
- Не давайте готовое решение, а подталкивайте к нему.
- В сложных ситуациях обращайтесь к человеку, который управляет всеми процессами в ревью.
- Используйте автотесты и линтеры. Это поможет не допустить до ревью неработающий код и сместить фокус проверки со стилистики на эффективность и оптимальность решения.
- В учебных проектах используйте чеклисты возможных ошибок. В реальной работе заранее договоритесь об общих подходах к разработке, задокументируйте их и применяйте на ревью.
