Створення code style у розробці

Технології 10 січня 2025

Добрий день,% username%

Хочу поділитися своїм успішним досвідом впровадження автоматичної перевірки стилів коду в проект і розповісти на які граблі наступали. Опублікувати 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. Виглядає ось так:

Що далі?

Є ідея зробити перевірник інтерактивним: щоб можна було відповісти на коментар робота «виправь», і робот би сам виправив помилку, якщо її можна виправити (наприклад, відсутній пробіл). Але, на жаль, я не знайшов інструментів, які можуть виправляти стилі в конкретному рядку. Якщо спільнота підкаже - буду радий

Посилання: