Можно начать с того, чтобы описать ключевые моменты по задаче: чего хотели достичь, какие решения решили применить и почему. Излишне подробно описывать не нужно, но небольшое количество информации для контекста поможет ревьюеру видеть картину более широко.
Если ревьюер не знаком с проектом, то можно предложить взглянуть на код его глазами и ответить на вопросы, которые возникают при прочтении изменений в коде. Такие вопросы могут возникать в местах, где применены технические решения специфичные для проекта, но не являющиеся общими для всей компании.
Также я бы рекомендовал воспользоваться практикой self‑review и почистить код до приглашения ревьюера, для того чтобы не отвлекать его на мелочи типа опечаток и форматирования.
Если отвечать на вопрос о выборе участка кода для проверки, то нужно понять каких целей вы хотите достичь подключая внешнего ревьюера: разделение опыта, погружение в проект, контроль качества, или всё вместе? И исходя из этого можно подключать внешнего ревьюера например только на крупные задачи, либо на все, если нужен постоянный контроль качества и погружение ревьюера в специфику проекта.
Внешний ревьюер может оценивать код как с точки зрения соответствия стандартам компании, так и с точки зрения соответствия постановки задачи, а также внутренним правилам команды. Для последнего — можно составить чек‑лист, который будет ссылаться как на стандарты компании, так и описывать правила разработки принятые внутри команды. Ссылку на чек‑лист можно добавить в ридми проекта, а также передавать ревьюеру при его приглашении.
Резюмируя, я бы рекомендовал:
Аннотировать ключевые моменты по задаче, в идеале при помощи описания технического дизайна
Составить чек‑лист с правилами разработки внутри команды и прикладывать его при приглашении ревьюера
Выявить цели, которых вы хотите достичь применением практики и в зависимости от них выбирать фрагменты кода, которые должны быть проверены
Самостоятельно проверить написанный код до передачи его внешнему ревьюеру
В заключение, я хотел бы поделиться нашим опытом: мы используем как код‑ревью участниками команд, так и подключение внешних ревьюеров. Внешних ревьюеров мы обычно приглашаем когда было применено какое‑то интересное техническое решение или необычный подход в решении задачи, для того чтобы поделиться экспертизой. Такой комбинированный подход позволяет не тратить время на погружение в специфику проекта у небольших задач, но при этом распространяет опыт и насмотренность на код за границы команды.
Мы тоже задавались вопросом — в каких случаях явно выделенный этап проектирования повышает эффективность разработки, а в каких понижает и при этом не даёт преимуществ в долгосрочной перспективе.
Начну с общих соображений.
Длительность проектирования тем больше, чем сложнее реализуемая задача.
В общем случае цена исправления ошибочного решения увеличивается со сложностью задачи.
Небольшие, но частые изменения в проекте оказывают влияние на его архитектуру. Поэтому важно реализовывать их качественно.
В нашей команде изначально мы внедряли процесс проектирования для крупных задач, так как его необходимость там наиболее очевидна. При этом, в небольших задачах тоже иногда встречались неудачные решения, которые приходилось дорабатывать по результатам код-ревью, либо со временем при рефакторинге. Поэтому следующей итерацией было описание дизайна вообще для всех задач, где было больше одного изменения в коде. И это дало интересный результат, поскольку в процессе дизайн-ревью мы действительно несколько раз отлавливали неудачные решения, то есть экономили время на последующей реализации. Сейчас описание дизайна у нас остаётся на усмотрение разработчика.
Мне кажется что для небольших и однотипных задач можно применить такой подход: Если дизайн по задачам такого типа не проектировался, описать его и вынести в техническую документацию проекта. В дальнейшем, при реализации похожих задач можно заглядывать в этот документ и использовать выбранные решения. Преимуществом тут будет то, что дизайн описывается более абстрактно чем код, поэтому переносить его с задачи на задачу (пусть даже мысленно) проще.
Если говорить про пример из статьи, то это была крупная задача. Проектировал её один человек, затем было ревью с командой и раздача декомпозированных подзадач.
На описание дизайна небольших задач уходит от 30 минут до двух часов. И здесь важно чтобы коллеги по команде смогли быстро подключиться и прочесть дизайн. При этом, можно фиксировать кто проводил дизайн-ревью и подключать этого же специалиста для код-ревью. Тогда экономится время, поскольку он уже знаком с задачей и остаётся проверить совпала ли фактическая реализация с дизайном описанным до её начала.
Спасибо за вопрос!
Можно начать с того, чтобы описать ключевые моменты по задаче: чего хотели достичь, какие решения решили применить и почему. Излишне подробно описывать не нужно, но небольшое количество информации для контекста поможет ревьюеру видеть картину более широко.
Если ревьюер не знаком с проектом, то можно предложить взглянуть на код его глазами и ответить на вопросы, которые возникают при прочтении изменений в коде. Такие вопросы могут возникать в местах, где применены технические решения специфичные для проекта, но не являющиеся общими для всей компании.
С этими двумя пунктами может помочь документ с описанием технического дизайна по задаче — он покажет ваши намерения по реализации, а также объяснит причины принятия тех, или иных решений.
Также я бы рекомендовал воспользоваться практикой self‑review и почистить код до приглашения ревьюера, для того чтобы не отвлекать его на мелочи типа опечаток и форматирования.
Если отвечать на вопрос о выборе участка кода для проверки, то нужно понять каких целей вы хотите достичь подключая внешнего ревьюера: разделение опыта, погружение в проект, контроль качества, или всё вместе? И исходя из этого можно подключать внешнего ревьюера например только на крупные задачи, либо на все, если нужен постоянный контроль качества и погружение ревьюера в специфику проекта.
Внешний ревьюер может оценивать код как с точки зрения соответствия стандартам компании, так и с точки зрения соответствия постановки задачи, а также внутренним правилам команды. Для последнего — можно составить чек‑лист, который будет ссылаться как на стандарты компании, так и описывать правила разработки принятые внутри команды. Ссылку на чек‑лист можно добавить в ридми проекта, а также передавать ревьюеру при его приглашении.
Резюмируя, я бы рекомендовал:
Аннотировать ключевые моменты по задаче, в идеале при помощи описания технического дизайна
Составить чек‑лист с правилами разработки внутри команды и прикладывать его при приглашении ревьюера
Выявить цели, которых вы хотите достичь применением практики и в зависимости от них выбирать фрагменты кода, которые должны быть проверены
Самостоятельно проверить написанный код до передачи его внешнему ревьюеру
В заключение, я хотел бы поделиться нашим опытом: мы используем как код‑ревью участниками команд, так и подключение внешних ревьюеров. Внешних ревьюеров мы обычно приглашаем когда было применено какое‑то интересное техническое решение или необычный подход в решении задачи, для того чтобы поделиться экспертизой. Такой комбинированный подход позволяет не тратить время на погружение в специфику проекта у небольших задач, но при этом распространяет опыт и насмотренность на код за границы команды.
Спасибо за Ваш вопрос!
Мы тоже задавались вопросом — в каких случаях явно выделенный этап проектирования повышает эффективность разработки, а в каких понижает и при этом не даёт преимуществ в долгосрочной перспективе.
Начну с общих соображений.
Длительность проектирования тем больше, чем сложнее реализуемая задача.
В общем случае цена исправления ошибочного решения увеличивается со сложностью задачи.
Небольшие, но частые изменения в проекте оказывают влияние на его архитектуру. Поэтому важно реализовывать их качественно.
В нашей команде изначально мы внедряли процесс проектирования для крупных задач, так как его необходимость там наиболее очевидна. При этом, в небольших задачах тоже иногда встречались неудачные решения, которые приходилось дорабатывать по результатам код-ревью, либо со временем при рефакторинге. Поэтому следующей итерацией было описание дизайна вообще для всех задач, где было больше одного изменения в коде. И это дало интересный результат, поскольку в процессе дизайн-ревью мы действительно несколько раз отлавливали неудачные решения, то есть экономили время на последующей реализации. Сейчас описание дизайна у нас остаётся на усмотрение разработчика.
Мне кажется что для небольших и однотипных задач можно применить такой подход: Если дизайн по задачам такого типа не проектировался, описать его и вынести в техническую документацию проекта. В дальнейшем, при реализации похожих задач можно заглядывать в этот документ и использовать выбранные решения. Преимуществом тут будет то, что дизайн описывается более абстрактно чем код, поэтому переносить его с задачи на задачу (пусть даже мысленно) проще.
Если говорить про пример из статьи, то это была крупная задача. Проектировал её один человек, затем было ревью с командой и раздача декомпозированных подзадач.
На описание дизайна небольших задач уходит от 30 минут до двух часов. И здесь важно чтобы коллеги по команде смогли быстро подключиться и прочесть дизайн. При этом, можно фиксировать кто проводил дизайн-ревью и подключать этого же специалиста для код-ревью. Тогда экономится время, поскольку он уже знаком с задачей и остаётся проверить совпала ли фактическая реализация с дизайном описанным до её начала.
Надеюсь, ответил на Ваш вопрос.
Спасибо!