Обзор кода в комментариях

в 13:51, , рубрики: code review, DVCS, Git, Mercurial, simple, Программирование, разработка, метки: , , , ,

Обзор кода полезен и делать его можно разными способами: патчами по почте, сидя рядом лицом к лицу или используя специализированные инструменты/плагины. Каждый способ имеет свои плюсы и минусы, однако мы предлагаем ещё один, который позволяет нам использовать то, что у нас уже есть.

Предусловия

Метод будет интересен небольшой команде, использующей распределённую систему контроля версий (git, mercurial, bazaar) с внедренной методологией разработки фич/задач/багов в ветках (например, gitflow). Редакторы кода в команде поддерживают парсинг комментариев на предмет определённых ключевых слов (например, TODO). А полнофункциональные специализированные инструменты для обзора кода не могут быть внедрены, так как платны и не имеют строки в бюджете; либо бесплатны, но не просты в установке или имеют сомнительное удобство использования; или же в конкретном случае могут быть воробейной царь-пушкой.

Процесс

Общая идея — фичи (баги, таски) разрабатываются в отдельных ветках, а-ля gitflow, а затем публикуются на некий сервер — можно даже центральный. Рецензент пишет комментарии в стиле TODO, но с особым тегом, например «REV»:

$ourcoolcode = 123;
// REV Что это тут у нас такое?
echo $ourcoolcode;

Синтаксис комментариев

/**
 * $TAG $status $title
 * $commentor1 $comments
 * $commentorN $comments
 */

  • $TAG — уникальный для кода проекта, не TODO, не XXX, и т.д, а, например, REV. Не должен существовать в комментариях в текущем коде проекта.
  • $status — необязательный параметр, который может указывать на статус: “+” — вопрос закрыт или проблема разрешена; “!” — у нас проблема, причем количество знаков может обозначать степень серьезности проблемы.
  • $title — заголовок вопроса/проблемы.
  • $commentor1 / $commentorN — (необязательно) некое обозначение авторов комментариев, чтобы одни комментарии от других отличать.
  • $comments — либо комментарии автора вопроса/проблемы, когда в заголовке все не помещается, либо коментарии того, кто отвечает.

Комментарии могут быть как однострочными, так и многострочными, что зависит от конкретного языка.

Обзор кода в комментарияхЛюбая современная IDE умеет экстрактить и фильтровать TODO. Это точно умеет Eclipse и Netbeans, а JetBrains и прочие платные редакторы просто обязаны это делать. В итоге можно меняться комментами в ветке, пока всё не станет ясно и они не кончатся. По окончании процесса, когда код станет лучше, ветку можно смело сжимать (squash) и вливать (merge) в основную (develop). Все комменты по окончании стираются и не должны попасть в код, что можно зафорсить хуками.

Абстрактный пример в вакууме

Плюсы и минусы

Достоинства метода:

  • минимальная стоимость внедрения — используются абсолютно родные инструменты — редактор со стандартными настройками/плагинами и система контроля версий;
  • вопросы и дефекты видны сразу в редакторе;
  • работает в самолёте (: также как git и другие dvcs);
  • при работе с кодом мы можем открывать режим сравнения, видеть что изменено и здесь же писать спец-комментарии

И конечно недостатки (с вариантами обходов):

  • наколеночность и то, что мы теперь настраиваем не некий инструмент, а свои редакторы и ставим хуки в репозиториях, хотя: хуки можно написать один раз и выложить на гитхаб; настройку инструментов также описать один раз и выложить на гитхаб вики с картинками;
  • надо поддерживать некую дисциплину и соблюдать конвенции, которые в обычных инструментах просто форсятся, хотя аболютно всё можно организовать с помощью хуков: комменты могут остаться? не пускать в develop/master коммиты с ними; журнал коммитов может забиваться “левыми” коммитами? сжимать их и вливать уже полноценные в основные ветки;
  • синтаксис и проблема длинных комментариев или обсуждений;
  • сохранение истории: как вариант, в финальном коммите, тело поболее сделать и расписать что обсуждали и к чему пришли.

Заключение

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

Автор: garex

* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js