Наверное, в любом коллективе рано или поздно встает вопрос о создании и утверждении стандартов кодирования.
На первый взгляд задача довольно тривиальная.
Но только в том случае, если это будет принято на ранней стадии разработки проекта.
Тогда разработчикам достаточно выбрать и применить один из популярных стандартов, и чаще всего этот выбор за них делает используемый ими фреймворк.
В нашем случае все не так просто.
Проект, над которым мы работаем, начал свою жизнь до того, как различные стандарты и описания лучших практик в среде разработки стали уделять много внимания.
В том числе, задолго до появления столь популярных ныне стандартов PSR для PHP. По этим причинам задача стандартизации кода не ставилась на ранних этапах, но сейчас она представилась нашей команде как вызов.
В этой публикации мы поговорим о том, как мы пришли к пониманию необходимости единого стиля кода и разработали методы его постепенного внедрения в масштабный проект. Этот опыт может быть интересен тем, кто еще не использует стандартизацию, но уже чувствует в ней необходимость.
Что мы имеем
- Кодовая база (PHP, MySQL, HTML, SCSS, JavaScript), сформированная за 10 лет;
- Негласное понимание общего формата, который включает в себя:
— Snake_case для имен переменных и функций в бэкенде;
— основные правила форматирования (отступы, пробелы, дефисы);
— регламент написания sql-запросов;
— названия таблиц и столбцов;
— Венгерское обозначение переменных, содержащих входные данные.
Это лишь несколько примеров из множества нюансов, которые существуют в каждом проекте.
Чего у нас нет?
Официально принятый стиль, зафиксированный на бумаге и обязательный к исполнению.Возможно, именно поэтому негласный формат непостоянен и меняется со временем — его «эволюцию» можно легко отследить с помощью системы контроля версий.
Осознание проблемы
В какой-то момент мы начали замечать, что довольно часто обсуждаем код в контексте форматирования, а это отнимает много времени.В то же время команда начала активно расширяться.
Наши новые коллеги имели свои собственные привычки кодирования и не были знакомы с практиками, сложившимися в нашей команде.
В результате их стиль кодирования противоречил нашим «негласным правилам», что существенно влияло на производительность.
Например, объединение разных стилей форматирования и использование языковых конструкций внутри одного блока кода привело к значительному снижению его читабельности:
Но если внутри команды всегда есть возможность оперативно обсудить и решить спорные вопросы, то при работе со сторонними разработчиками сложностей возникает гораздо больше.for ($i=0; $i<$num; $i++) { if (in_array($items[$i]['value'],$filtered)) continue; array_push($valid, $items[$i]); if(!$items[$i]['in_menu']) continue; $in_menu[] = $items[$i]; }
К разработке клиентской части мы привлекали сторонних специалистов, и именно во фронтенд-коде появилось наибольшее разнообразие стилей.
Например, имена классов в одном блоке HTML-кода могут сочетать в себе разные обозначения и даже разные реализации BЭMa. Но вот основная сложность, которая возникла при сотрудничестве со сторонними специалистами: как поддерживать код, написанный с использованием практик и подходов, которые знают не все разработчики проектов? Непоследовательный выбор методики в верстке и последующем редактировании иногда приводил к чему-то вроде этого: <div class="i-article__item__item__content">.
</div>
или <div class="i-article__about-article-block_dropdown-handler">.
</div>
Если в первом случае можно проследить применение БЭМ, то во втором вообще невозможно понять, «что происходит».
Кроме того, использование BЭM в именах классов в HTML иногда не влекло за собой никаких преимуществ в CSS. Класс из первого варианта, содержащий описание вложенности элемента, по-прежнему описывался с помощью вложенных стилей в CSS: .
i-article__item .
i-article__item__item .
i-article__item__item__content { .
}
Как такое могло произойти? Пример из опыта: удаленный верстальщик выполнил свою работу частично, не успев доделать мобильную версию интерфейса.
К работе подключился еще один специалист, добавив новый код в своем «уникальном» стиле.
На следующем этапе при портировании макета на динамический движок возникла необходимость что-то быстро подкорректировать, и этим занимался бэкенд-разработчик, который, естественно, не вникал в «тонкости» используемого вёрсткой формата.
дизайнеры.
Стало очевидно, что одним из наших главных приоритетов является недопущение подобных несоответствий в будущем.
Отсрочка принятия решения может привести к потере производительности и увеличению времени разработки.
В команде окончательно сформировалось понимание необходимости утверждения единого формата кода.
Разработка решения
Поскольку объем кода измеряется сотнями тысяч строк, найти и переработать все случаи нарушения стиля не удалось даже с помощью автоматических инструментов.Поэтому мы решили начать применять единый стиль к новому коду, одновременно обновляя небольшие фрагменты устаревшего кода, которые имели отношение к поставленной задаче.
Далее нам предстояло определиться с самим форматом.
Оказалось, что у членов команды были существенные разногласия во взглядах на «правильный стиль»: одни предпочитали CamelCase, другие настаивали на использовании Snake_case во всем, даже в клиентском JavaScript. 
В этом случае большую роль играет уровень и бэкграунд разработчика.
Как вы уже догадались, во втором случае речь идет о backend-программисте с большим опытом работы.
Разногласия возникли по многим пунктам, но в одном согласились единогласно: вы не хотите использовать одно из существующих руководств по стилю «как есть»; вы должны сохранить уникальный, хотя и не полностью развитый стиль вашего проекта.
Поэтому было решено документировать то, что использовалось за кулисами, а неочевидные и спорные моменты выносить на обсуждение.
За достаточно короткий срок мы создали собственное руководство по стилю для php, sql и частично JavaScript кода.
Следующими были CSS и SCSS. В формировании CSS-кода участвовало наибольшее количество разработчиков, в том числе удаленных, а CSS — это язык, можно сказать, допускающий различные вольности.
Очень скоро стало ясно, что соблюдение единого стиля возможно.
только с максимально понятным и подробным описанием всех правил, со множеством примеров, что делать и чего не делать.
Обсуждение затянулось, и по ряду пунктов команде не удалось прийти к единому мнению.
В результате для SCSS и CSS мы решили использовать готовый сторонний документ со своими небольшими корректировками.
Мы использовали Сасс , CSS , а рассмотрение и согласование поправок заняло у команды не более 3 часов.
Контроль исполнения
Для контроля за соблюдением принятых правил мы решили использовать инструменты автоматической проверки.Сегодня существует достаточно большой выбор таких инструментов, многие из которых работают в формате облачных сервисов и легко интегрируются с популярными платформами хостинга кода и непрерывной интеграции.
Выбор пал на SonarQube — платформу статического анализа кода, которая поддерживает разные языки программирования и предлагает несколько форматов использования, в том числе self-hosted, а также облачную версию (SonarCloud).
Кроме того, есть интеграция с нашей CI-платформой (Teamcity) и возможность предварительной проверки в редакторе кода (SonarLint).
Процесс установки системы вместе с пакетом плагинов занял не более получаса, интеграция с Teamcity заняла чуть больше часа.
Нам пришлось создать так называемые «профили качества» — набор правил для каждого языка, используемого при тестировании.
В противном случае результат анализа не будет отражать реальную картину.
Настройка профилей в соответствии с нашими предпочтениями заняла около трёх часов.
Интересно, что PHP предлагает 3 варианта по умолчанию: «PSR2», «Drupal» и фирменный «Sonar way» — многие наверняка смогут использовать систему «из коробки».
После установки и настройки наступил «момент истины» — тест проверки качества кода на соответствие сформулированным правилам.
Запустите команду гидролокатор-сканер и ждать.
На индексацию файлов и проверку более 500 тысяч строк кода ушло около 4 минут. Результат анализа доступен в довольно приятном и удобном интерфейсе: 
Представленный результат стал для нас ожидаемым следствием внедрения стиля кода и автоматического управления на поздней стадии разработки проекта.
В дальнейшей работе с этим инструментом нас больше всего будут интересовать индикаторы в правой части экрана, выделенные желтым цветом.
Эти данные отражают анализ нового кода, добавленного после предыдущей оценки.
Что дальше?
Наша цель — следить за качеством нового кода и постепенно улучшать общую статистику, представленную в левой части экрана.В течение двух недель мы протестируем систему в полевых условиях и оценим преимущества ее внедрения.
В следующем посте мы поделимся результатами тестирования системы, подведем итоги и расскажем о трудностях, с которыми столкнулись.
Если у вас был подобный опыт реализации стиля кода, будет интересно обсудить его в комментариях! Теги: #стиль кода #статический анализ кода #php #sonarqube #Управление разработкой #Разработка веб-сайтов #программирование #Идеальный код #ИТ-стандарты
-
Узнайте О Фазане
19 Oct, 24 -
Новое Отображение Персонажей В Eve Online
19 Oct, 24
