Является ли обзор кода, который использует только комментарии кода хорошей идеей?

Предпосылками

• Команда использует DVCS
• IDE поддерживает анализ комментариев (например, TODO и т. Д.)
• Такие инструменты, как CodeCollaborator, дороги для бюджета
• Инструменты типа gerrit слишком сложны для установки или не пригодны для использования

Workflow

• Автор публикует где-то в центральной ветке репо
• Рецензент получить его и начать обзор

• В случае возникновения какого-либо вопроса / рецензента, создайте комментарий со специальной меткой, например, «REV». Такой ярлык НЕ ДОЛЖЕН быть в рабочем коде - только на этапе проверки:

  $somevar = 123;
  // REV Why do echo this here?
  echo $somevar;
  

• Когда рецензент заканчивает публиковать комментарии - он просто коммит с глупым сообщением "комментарии" и отталкивает назад

• Автор возвращает ответвление функции и отвечает на комментарии аналогичным образом или улучшает код и возвращает его обратно.
• Когда комментарии «REV» исчезли, мы можем думать, что обзор успешно завершен.
• Автор в интерактивном режиме перебазирует ветку функции, раздавливает ее, чтобы удалить эти коммиты «комментария», и теперь готов объединить функцию для разработки или выполнения любого действия, которое обычно может быть после успешного внутреннего просмотра

Поддержка IDE

Я знаю, что пользовательские теги комментариев возможны в eclipse & netbeans. Конечно, это также должно быть в семье BlablaStorm.

Вопросов

1. Как вы думаете, эта методология жизнеспособна?
2. Вы знаете что-то подобное?
3. Что в этом можно улучшить?

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

Есть еще несколько недостатков:

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

• Я не верю, что рецензент имеет достаточно отзывов от рецензента, чтобы знать, как на самом деле были применены рецензированные пункты .

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

  Алиса предлагает альтернативный синтаксис и передает код обратно Эрику. Он переписывает код, используя этот альтернативный синтаксис, который, как он считает, понимает правильно, и удаляет соответствующий // BLAкомментарий.

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

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

• Люди все еще люди. Я почти уверен, что некоторые из этих комментариев окажутся в рабочем коде, а некоторые останутся мусором, будучи полностью устаревшими .

  Конечно, та же проблема существует с любым другим комментарием; например, в производстве есть много комментариев TODO (включая самый полезный: «TODO: прокомментируйте код ниже.») и множество комментариев, которые не были обновлены, когда был соответствующий код.

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

• Это не заменяет очную проверку (но та же проблема относится и к любой другой, более формальной проверке, которая не проводится лицом к лицу).

  Особенно, если исходный отзыв требует объяснения, рецензент и рецензент начнут своего рода обсуждение . Мало того, что вы окажетесь с большими комментариями BLA, но эти обсуждения также загрязнят журнал контроля версий .

• Вы также можете столкнуться с незначительными проблемами с синтаксисом (который также существует для комментариев TODO). Например, что если длинный комментарий "// BLA" появляется в несколько строк, и кто-то решает написать его следующим образом:

  // BLA This is a very long comment which is way beyond 80 characters, so it actually
  // fills more then one line. Since the next lines start with slashes, but not "BLA"
  // keyword, the IDE may not be able to show those lines, and display only the first one.
  

• И, наконец, небольшая и очень личная заметка: не выбирайте «BLA» в качестве ключевого слова. Звучит ужасно. ;)

Я бы дополнил комментарии в коде сопроводительным документом. Это будет обобщать результаты и жить после того, как комментарии были удалены. Преимущества этого будут:

• Компактность. Если человек обычно не может проверить, что переданный указатель не равен нулю (или есть какая-то другая распространенная ошибка новичка на используемом вами языке), рецензент может оставить десятки комментариев REV на этот счет, и в документе можно сказать « Я нашел 37 мест, где указатели не проверялись первыми, не перечисляя их все
• место для похвалы. Такой комментарий REV this is a nice designкажется странным, но мои обзоры кода часто включают одобрение и исправления.
• интерактивность. Ваш примерный комментарий: «Зачем ты это сделал?» и это очень типичный. Подход только для комментариев не поддерживает разговор. Человек может изменить свой код и удалить комментарий или удалить комментарий. Но "почему ты это сделал?" и "пожалуйста, измени это, это неправильно" - это не одно и то же.
• ведение учета. Более поздний рецензент может проверить, действительно ли код был изменен, или комментарии были просто удалены. Они также могут проверить, что комментарии были «приняты к сведению», и разработчик больше не делает те же ошибки в последующем обзоре.

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

Другие говорили об ограничениях этого подхода. Вы упомянули, что такие инструменты, как gerrit, было трудно установить - я предлагаю вам взглянуть на phabricator (http://www.phabricator.com). Это система проверки кода, которую Facebook использовал годами и недавно был открыт. Это не сложно установить, имеет отличные рабочие процессы и решает все проблемы, упомянутые в других комментариях.