Добрый день, %username%
Хочу поделиться своим успешным опытом внедрения автоматической проверки стилей кода в проект и рассказать на какие грабли наступали. Опубликовать opensource сообществу инструменты, которые были созданы для решения задачи
Немного о нашем проекте: PHP сайт, лежит в git репозитории объемом 2Gb, состоит из 20k php файлов, возраст проекта- 10 лет, в данный момент у нас 15 разработчиков. Для code review используем atlassian stash. Всю разработку ведем в рамках отдельных веток, которые после прохождения code review вливаем в master и деплоим на прод
Для начала вопрос: а зачем? Зачем вообще следить за стилями кода?
Ответ для меня простой: код пишется один раз, а читается потом десятками людей на протяжении многих лет. Следовательно стоимость поддержки кода многократно превышает стоимость написания. А раз так — то стоит потратить немного времени и отформатировать код согласно некому стандарту
Первое на что наткнулись: а какой стандарт выбрать? Поступили так — создали свой стандарт, унаследованный от symfony, и вносим туда изменения согласно нашему представлению о прекрасном. Некоторые правила мы просто выбрасывали, как невозможные в нашем проекте для старых классов (например, то что любой класс должен быть внутри namespace). Благо phpcs представляет хорошие возможности по настройке стилей кода
Второе: а чем проверять код? Какие есть утилиты для этого? После недолгих поисков остановились на phpcs, так как есть нативная поддержка в phpstorm
Третье: а что проверять? Весь проект у нас огромный, писался десятилетие многими поколениями разработчиков. Ошибок в стилях там просто немерено. Потому решили, что проверять нужно только те строки, которые изменил разработчик в рамках данной задачи
Третье: а как собственно проверять код?
Тут были разные варианты
Немного об архитектуре инструмента:
1) При пуше в некоторую ветку webhook дергает phpcs-stash и передает название ветки, куда был сделан push
2) phpcs-stash запрашивает по API у stash все рецензии (pull requests) с этой веткой, проходится по всем файлам (дергает их так же из stash по API), проверяет стили, отписывается где нашел ошибку. В случае если ошибок нет — аппрувит рецензию. Отписывается робот только в измененных строках
Результат выглядит вот так:
3) При повторном пуше робот заново проверяет все рецензии, удаляет комментарии об исправленных ошибках
Для любителей картинок:
При таком подходе у нас остается возможность настройки родной интеграции между stash и jira (например: запретить закрывать задачу если рецензия кода не одобрена роботом). И есть отличная возможность анализировать какие ошибки случаются чаще всего, что бы дорабатывать правила проверки
Так как система проверки не знает ни о чем кроме atlassian stash, было решено сделать её ориентированной в open source. Изначально делалось только для PHP, но парням из соседнего отдела понравилось и они сделали поддержку проверки C++ кода
Для быстрой обратной связи используется phpstorm, который умеет интегрироваться с phpcs. Выглядит вот так:
Что дальше?
Есть идея сделать проверяльщик интерактивным: чтобы можно было ответить на комментарий робота «исправь», и робот бы сам исправил ошибку, если её можно исправить (например, отсутствующий пробел). Но, к сожалению, я не нашел инструментов, которые могут исправлять стили в конкретной строке. Если сообщество подскажет — буду рад
Ссылки:
Хочу поделиться своим успешным опытом внедрения автоматической проверки стилей кода в проект и рассказать на какие грабли наступали. Опубликовать opensource сообществу инструменты, которые были созданы для решения задачи
Немного о нашем проекте: PHP сайт, лежит в git репозитории объемом 2Gb, состоит из 20k php файлов, возраст проекта- 10 лет, в данный момент у нас 15 разработчиков. Для code review используем atlassian stash. Всю разработку ведем в рамках отдельных веток, которые после прохождения code review вливаем в master и деплоим на прод
Для начала вопрос: а зачем? Зачем вообще следить за стилями кода?
Ответ для меня простой: код пишется один раз, а читается потом десятками людей на протяжении многих лет. Следовательно стоимость поддержки кода многократно превышает стоимость написания. А раз так — то стоит потратить немного времени и отформатировать код согласно некому стандарту
Первое на что наткнулись: а какой стандарт выбрать? Поступили так — создали свой стандарт, унаследованный от symfony, и вносим туда изменения согласно нашему представлению о прекрасном. Некоторые правила мы просто выбрасывали, как невозможные в нашем проекте для старых классов (например, то что любой класс должен быть внутри namespace). Благо phpcs представляет хорошие возможности по настройке стилей кода
Второе: а чем проверять код? Какие есть утилиты для этого? После недолгих поисков остановились на phpcs, так как есть нативная поддержка в phpstorm
Третье: а что проверять? Весь проект у нас огромный, писался десятилетие многими поколениями разработчиков. Ошибок в стилях там просто немерено. Потому решили, что проверять нужно только те строки, которые изменил разработчик в рамках данной задачи
Третье: а как собственно проверять код?
Тут были разные варианты
- Как известно, git поддерживает серверные хуки. Можно проверять стили на стороне сервера и не давать запушить, пока ошибки не будут исправлены. Но такой подход мне не понравился, так как бодаться пушами с гитом в консоли не очень-то удобно :) Плюс тут невозможно сделать обходной путь, когда исправить все ошибки в стилях по каким-то причинам невозможно (например, нужно переименовать имя метода, который используется в 100500 файлах)
- После некоторых размышлений решили, что идеальный вариант, когда робот будет сам отписываться в pull request про найденные ошибки в стилях, которые уже разработчик должен будет исправлять. При этом на первом этапе мы разрешали какие-то ошибки не исправлять, если это требовало существенно рефакторинга, дорабатывали удобные для нас правила проверки. Так родился инструмент — phpcs-stash
Немного об архитектуре инструмента:
1) При пуше в некоторую ветку webhook дергает phpcs-stash и передает название ветки, куда был сделан push
2) phpcs-stash запрашивает по API у stash все рецензии (pull requests) с этой веткой, проходится по всем файлам (дергает их так же из stash по API), проверяет стили, отписывается где нашел ошибку. В случае если ошибок нет — аппрувит рецензию. Отписывается робот только в измененных строках
Результат выглядит вот так:
3) При повторном пуше робот заново проверяет все рецензии, удаляет комментарии об исправленных ошибках
Для любителей картинок:
При таком подходе у нас остается возможность настройки родной интеграции между stash и jira (например: запретить закрывать задачу если рецензия кода не одобрена роботом). И есть отличная возможность анализировать какие ошибки случаются чаще всего, что бы дорабатывать правила проверки
Так как система проверки не знает ни о чем кроме atlassian stash, было решено сделать её ориентированной в open source. Изначально делалось только для PHP, но парням из соседнего отдела понравилось и они сделали поддержку проверки C++ кода
Для быстрой обратной связи используется phpstorm, который умеет интегрироваться с phpcs. Выглядит вот так:
Что дальше?
Есть идея сделать проверяльщик интерактивным: чтобы можно было ответить на комментарий робота «исправь», и робот бы сам исправил ошибку, если её можно исправить (например, отсутствующий пробел). Но, к сожалению, я не нашел инструментов, которые могут исправлять стили в конкретной строке. Если сообщество подскажет — буду рад
Ссылки:
- phpcs-stash — https://github.com/WhoTrades/phpcs-stash
- REST API Atlasisan Stash — https://developer.atlassian.com/stash/docs/latest/reference/rest-api.html
