Обзор кода полезен и делать его можно разными способами: патчами по почте, сидя рядом лицом к лицу или используя специализированные инструменты/плагины. Каждый способ имеет свои плюсы и минусы, однако мы предлагаем ещё один, который позволяет нам использовать то, что у нас уже есть.
Метод будет интересен небольшой команде, использующей распределённую систему контроля версий (git, mercurial, bazaar) с внедренной методологией разработки фич/задач/багов в ветках (например, gitflow). Редакторы кода в команде поддерживают парсинг комментариев на предмет определённых ключевых слов (например, TODO). А полнофункциональные специализированные инструменты для обзора кода не могут быть внедрены, так как платны и не имеют строки в бюджете; либо бесплатны, но не просты в установке или имеют сомнительное удобство использования; или же в конкретном случае могут быть воробейной царь-пушкой.
Общая идея — фичи (баги, таски) разрабатываются в отдельных ветках, а-ля gitflow, а затем публикуются на некий сервер — можно даже центральный. Рецензент пишет комментарии в стиле TODO, но с особым тегом, например «REV»:
Любая современная IDE умеет экстрактить и фильтровать TODO. Это точно умеет Eclipse и Netbeans, а JetBrains и прочие платные редакторы просто обязаны это делать. В итоге можно меняться комментами в ветке, пока всё не станет ясно и они не кончатся. По окончании процесса, когда код станет лучше, ветку можно смело сжимать (squash) и вливать (merge) в основную (develop). Все комменты по окончании стираются и не должны попасть в код, что можно зафорсить хуками.
Подчеркнем, что данный метод не предлагается, как единый и самый правильный, а является одним из вариантов в определённых условиях. Если вы знаете или уже использовали что-то подобное, но не формализировали, то опишите смело, также приветствуются улучшения метода. Даже если данный способ не подойдет вам, то возможно он натолкнет вас на какие-то иные идеи.
Предусловия
Метод будет интересен небольшой команде, использующей распределённую систему контроля версий (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 коммиты с ними; журнал коммитов может забиваться “левыми” коммитами? сжимать их и вливать уже полноценные в основные ветки;
- синтаксис и проблема длинных комментариев или обсуждений;
- сохранение истории: как вариант, в финальном коммите, тело поболее сделать и расписать что обсуждали и к чему пришли.
Заключение
Подчеркнем, что данный метод не предлагается, как единый и самый правильный, а является одним из вариантов в определённых условиях. Если вы знаете или уже использовали что-то подобное, но не формализировали, то опишите смело, также приветствуются улучшения метода. Даже если данный способ не подойдет вам, то возможно он натолкнет вас на какие-то иные идеи.