Сравнение анализаторов php-кода на примере разных веб-проектов

Содержание

Вызывает интерес ваш технический прогресс.
Как у вас там сеют брюкву, с кожурою, али без?

© «Сказка про Федота-стрельца, удалого молодца», Леонид Филатов

Программист — творческая профессия. Мы создаем что-то новое, руководствуясь своими знаниями, внутренним пониманием качества и поставленными дедлайнами. Дедлайны и знания пока оставим в стороне и сосредоточимся на качестве.

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

Ниже делимся статьей 2017 года.

«Что такое плохой/хороший код» — вопрос риторический. В нашей статье под качественным кодом мы будем понимать:

корректный с точки зрения платформы (без запросов к БД в шаблонах компонентов, запросы к БД с использованием индексов),

совместимый с актуальными версиями PHP (5.6, 7.0),

без ляпов (запросы к БД в цикле, запросы к внешним системам на хитах),

без уязвимостей (XSS, CSRF и т. д.).

С написанием хорошего кода отлично справляются самые опытные из нас: тимлиды. Но их мало (в штуках), а их время стоит дорого. У менее опытных разработчиков бывают проблемы со всем вышеперечисленным.

Как обеспечить качество кода с точки зрения методологии известно. Нужно развивать в команде процессы Continuous Integration: версионирование, тестирование, code review. Мы решили разобраться: какие инструменты подойдут для автоматизации code review при промышленной веб-разработке на PHP. А заодно проверим, как найденные инструменты оценят код нашего собственного сайта и нескольких решений из Marketplace 1С-Битрикс.

Инструменты для автоматизации code review PHP

Методика поиска инструментов

Мы нашли на github. com и packagist. org самые оцениваемые и самые скачиваемые проекты, связанные с анализом кода PHP. В обзор мы включили только надежные (созданы не вчера), поддерживаемые (есть сообщество и контрибьюторы) и популярные (количество звезд-”лайков”).

Выделили три категории инструментов:

проводящие анализ кода с целью поиска проблемных мест;

проверяющие совместимость версий PHP 5-7;

Инструменты для анализа PHP-кода

PHP Code Sniffer анализирует PHP, CSS и JavaScript-файлы на соответствие стандартам кодирования, находит и исправляет ошибки. Стандарт представляет собой совокупность sniff-файлов, задающих правила. Количество установок анализатора с 2016 года превысило

330 тысяч. Использование зафиксировано в

325 тысяч установок с начала 2016 года), так и у разработчиков (с 2017 года используется в

PHP Mess Detector определяет ошибки кода, неоптимальные и усложненные места, неиспользуемые переменные, методы, свойства. Позволяет создавать пользовательские правила. Поддерживает PHP 7. Сохраняет отчеты в трех форматах: текстовый, html, xml. С 2016 года пользователи установили

315 тысяч раз, используется в

PHP Metrics — инструмент статического анализа для PHP. Выдает информацию о проекте и используемых классах в виде сгенерированного сайта. Поддерживает PHP 7. С 2016 года зарегистрировано

260 тысяч скачиваний.

PHP Static Analysis Tool анализирует количество и типы параметров, передаваемых конструкторам, методам и функциям; типы, возвращаемые методами и функциями и т. д. Инструмент включает поддержку PHP 7 и предоставляет написание собственных правил. Количество скачиваний с 2016 года

150 тысяч раз, использован разработчиками в

PHP Copy Paste Detector выдает информацию о дублированных участках кода. Проект набирает популярность (количество установок с 2016 года составляет

100 тысяч раз, используется в

Phan — статический анализатор для PHP. Проверяет определение и доступность методов, функций, классов, traits, интерфейсов, констант, свойств и переменных, обнаруживает неиспользуемый код, проверяет код на обратную совместимость php7 к php5. С 2016 года зафиксировано

80 тысяч раз скачиваний.

PHP Dead Code Detector сообщает пользователю о функциях и методах, которые не используются в коде. Развитие проекта было остановлено в 2015 году. Начиная с 2016 года, количество установок пошло на спад.

Qafoo Quality Analyzer — инструмент, предназначенный для визуализации метрик исходного кода. Начиная с 2015 года, инструмент установлен пользователями

Инструменты для контроля совместимости кода с разными версиями PHP

PHP Compatibility — набор правил для PHP Code Sniffer, которые проверяют совместимость текущего кода с другими версиями PHP, включая PHP 7. Начиная с 2016 года, инструмент установлен пользователями

PHP 7 Compatibility Checker — инструмент для проверки кода PHP 5.3 – 5.6 на совместимость с PHP 7. Находит потенциальные проблемы в коде и генерирует отчеты, содержащие имена файлов, номера строк и краткое описание проблемы. При этом проблемы двух типов: ошибки, вызывающие серьезные проблемы (фатальная ошибка, ошибка синтаксиса и т. д.) и предупреждения, приводящие к логическим ошибкам. Начиная с 2016 года, инструмент установлен пользователями

Инструменты для поиска уязвимостей в PHP-коде

К сожалению нам не удалось найти ни одного проекта для анализа уязвимостей в PHP-коде, который заслуживал бы внимания. А жаль…

Что на выходе

PHP CS Fixer

файлы, в которых обнаружены ошибки;

правила, которые сработали;

изменения, затронувшие строки файла: удаленные, оставшиеся без изменений, добавленные строки.

PHP Code Sniffer

PHP Mess Detector

Отчет в PHP Mess Detector генерируется в одном из трех форматов: текстовый, html, xml. Полученный файл содержит информацию об обнаруженных проблемах в файлах. Проблема описывается начальной и конечной строкой, сработавшим правилом и поясняющим сообщением.

PHP Dead Code Detector

PHP Copy Paste Detector

В отчет по PHP Copy Paste Detector заносятся файлы, в которых дублируются строки.

PHP Static Analysis Tool

В отчете PHP Static Analysis Tool для каждого файла, в котором обнаружены ошибки, указывается номер строки в файле и описание ошибки. В конце отчета приводится общее количество найденных ошибок.

Результат работы в Phan может быть выведен в следующих режимах: ‘text’, ‘json’, ‘csv’, ‘codeclimate’, ‘checkstyle’, и ‘pylint’. В режиме ‘csv’ выводятся следующие столбцы: файл, строка, категория ошибки, phan-тип ошибки, сообщение.

PHP Compatibility

Результатом PHP Compatibility является список ошибок и предупреждений, найденных при проверке на совместимость с указанной версией PHP.

PHP 7 Compatibility Checker

При проверке на совместимость PHP 7 Compatibility Checker генерирует список нарушений в коде: указывается файл, строка, поясняющее сообщение и ошибочный код.

Qafoo Quality Analyzer

Qafoo Quality Analyzer генерирует отчет в формате xml, где для каждого файла приводится список обнаруженных ошибок с описанием.

PHP Metrics

PHP Metrics по окончании своего выполнения генерирует количественный отчет по метрикам и визуализирует полученные данные в виде созданного сайта.

Итоговая таблица сравнения инструментов

Инструмент объясняет, в чём ошибка

Что считать? Какая метрика?

Своя конфигурация правил, свои правила

Патч-файл с перечнем рекомендованных изменений

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

Таблицы с перечнем ошибок и отметкой, какие можно исправить автоматически

1. Количество ошибок2. Количество неисправимых ошибок

PHP 7 Compatibility Checker

Единый отчёт, по каждой ошибке: файл, строка, объяснение сути ошибки

PHP Copy Paste Detector

Единый отчёт с перечнем мест, где повторяется тот или иной участок кода

1. Количество “клонов”2. Количество повторяющихся строк

PHP Dead Code Detector

Перечень неиспользуемых функций и методов, файл с их объявлением и количество строк кода

1. Количество неиспользуемых функций/методов2. Количество строк, которые занимают такие функции/методы

Перечень ошибок: файл, строка, правило

PHP Static Analysis Tool

Перечень ошибок: файл, строка, правило

Qafoo Quality Analyzer

Перечень ошибок: файл, серьёзность ошибки, строка, правило

1. Количество ошибок2. Количество предупреждений

Перечень ошибок: файл, серьёзность ошибки, строка, правило

1. Количество ошибок категории low2. Количество ошибок категории normal3. Количество ошибок категории critical

Апробация инструментов на 1С-Битрикс

Каждый из инструментов был опробован на коде:

тиражных решений из Marketplace 1С-Битрикс (3 платных решения, 5 бесплатных),

современного сайта ИНТЕРВОЛГИ (на 1С-Битрикс),

устаревшего сайта ИНТЕРВОЛГИ (на самописной CMS).

Теперь к итогам сравнения решений. Мы считали не общее количество ошибок, а количество ошибок на 1000 строк кода.

ВАЖНО! Чтобы получить максимально показательную картину, мы суммировали ВСЕ замечания ВСЕХ 15 инструментов. Не удивляйтесь, что число ошибок часто больше числа строк.

Места распределились таким образом:

Старый сайт ИВ (703 ошибки на 1000 строк)

1С-Битрикс: Современный интернет-магазин (1457 ошибки на 1000 строк)

Новый сайт ИВ (1881 ошибки на 1000 строк)

1С-Битрикс: Корпоративный сайт (1998 ошибки на 1000 строк)

Платный ИМ (2506 ошибки на 1000 строк)

Платный ИМ (2525 ошибки на 1000 строк)

Платный ИМ (2682 ошибки на 1000 строк)

Бесплатный ИМ (3542 ошибки на 1000 строк)

1С-Битрикс: Информационный портал (3578 ошибки на 1000 строк)

Бесплатный ИМ (7361 ошибки на 1000 строк)

ВАЖНО! Чтобы получить максимально показательную картину, мы суммировали ВСЕ замечания ВСЕХ 15 инструментов. Не удивлятесь что число ошибок часто больше числа строк.

То, что лучшим стал старый сайт ИВ нас искренне удивило — мы ожидали прямо противоположного результата. У этого проекта 2 рекордных показателя — количество ошибок и количество строк кода. Так и вышло, что на 1000 строк кода проблем меньше всего. Но старый сайт — “почётный” участник, посмотрим на реальные результаты.

Настоящий победитель нашего исследования — 1С-Битрикс: Современный интернет-магазин. Что можно о нём сказать по результатам исследования:

Из 1000 строк в этом решении — в среднем 17 строк “копипасты”.

В 2 строках есть вызовы устаревшего API.

Есть 6 нарушений при работе с методами и полями.

284 строки кода можно отформатировать автоматически с помощью PHP CS Fixer.

Почти нет проблем с совместимостью PHP.

Худшим решением по мнению “жюри” признан бесплатный ИМ из ТОПа маркетплейса.

Добавим ложку дёгтя в бочку мёда компании 1С-Битрикс — вторым с конца оказалось тоже их решение, на которой выросло не одно поколение программистов.

Предпоследнее место — 1С-Битрикс: Информационный портал

Отличить настоящие ошибки от ложного срабатывания было сложно в PHP Dead Code Detector — тут оказывались обработчики событий, агенты, конструкторы и инсталляторы, которые явным образом нигде не вызываются в коде или вызываются извне модулей.

Насчёт PHP Static Analysis Tool уже было сказано, что почти все его ошибки были “ложными срабатываниями”.

Хорошо показал себя PHP Mess Detector: отследил мелкую, но неприятную ошибку статического вызова динамических методов и наоборот. В то же время он ругался на каждый else, так как “else is never necessary and you can simplify the code to work without else”.

Главный “хлеб” таких инструментов, как Qafoo Quality Analyzer, PHP Code Sniffer, PHP CS Fixer: превышение длины строк, переводы строк в конце файла, короткие-длинные открывающие php-теги, пробелы после ключевых слов if, for, while и т. п. Из предлагаемого инструментами набора правил мы выбрали наиболее похожие на стандарт оформления кода 1С-Битрикс, но всё равно получили около 50% ложных срабатываний.

Полезную статистику предоставляет PHP Metrics, если в вашей команде есть понимание, сколько операторов для класса уже “много”, а сколько — “ещё нормально”. Аналогично с цикломатической сложностью.

Вывод

Смысл затеи с инструментами проверки качества кода был в том, чтобы выяснить какой инструмент стоит выбрать для автоматизации Code Review. Эту цель мы достигли и свой выбор остановили на PHP CS Fixer и PHP Code Sniffer. Они адекватны задаче, популярны, развиваются, их можно расширять, и есть масса уже готовых тестов. Осталось только адаптировать их к реалиям разработки сайтов на 1С-Битрикс: Управление Сайтом.

Теперь, с той же обстоятельностью и упорством, с которыми мы писали этот обзор, будем внедрять эти инструменты в свою командную разработку.

Коды ошибок и статусы

Пример кода статуса в заголовке curl

Коды статусов не отображаются в тебе ответа. Они содержатся в хэдере, который может быть не видим по умолчанию.

Заголовок ответа выглядит следующим образом:

Коды состояния довольно тонкие, но когда разработчик работает с API, коды могут быть единственным «интерфейсом», который имеет разработчик. Если получится контролировать сообщения, которые видит разработчик, это будет большой победой юзабилити

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

Можно посмотреть список общих кодов состояния REST API здесь и общий список кодов HTTP статусов здесь. Хотя, возможно, было бы полезно включить несколько стандартных кодов состояния, нет необходимости в полном документировании всех стандартных кодов состояния, особенно если они редко запускаются в API.

Где перечислять HTTP-ответ и коды ошибок

Практичнее, если API будут иметь одну страницу с ответами и кодами ошибок ко всему API. Отдельная страница с перечнем кодов состояния (вместо добавления кода состояния в каждую конечную точку) позволяет более детально описать каждый код без переполнения других частей документации. Такой подход уменьшает избыточность и ощущение информационной перегрузки.

С другой стороны, если какие-то коды состояния и ошибок больше подходят к определенным конечным точкам, чем другие, имеет смысл вывести такие коды состояния и ошибок на страницы с описаниями конечных точек.

Такая стратегия может заключаться в том, чтобы привлечь внимание к каким-либо особенно важным кодам состояния или ошибок для конкретной конечной точки, а затем перейти к централизованной странице «Коды ответов и состояний» для получения полной информации.

Где взять коды ошибок и статусы

Коды состояния и ошибок могут быть неочевидны в документации API. Вероятно, придется попросить разработчиков предоставить список всех кодов состояния и ошибок, которые уникальны для API. Иногда разработчики хардкодят коды состояния и ошибок непосредственно в программном коде, и у них нет простых способов передать полный список (что также затрудняет локализацию).

В результате может потребоваться танцы с бубнами, чтобы найти все коды. В частности, возможно придется сломать API, чтобы увидеть все возможные коды ошибок. Например, если превысить ограничение скорости для определенного запроса, API может вернуть специальную ошибку или код состояния. Такой пользовательский код обязательно нужно задокументировать. В разделе устранения неполадок в API можно специально разместить примеры получения кодов ошибок.

Как перечислять коды ошибок

Коды статусов и ошибок можно привести в виде списка определений или таблицы, например так:

Status code	Значение
200	Успешный запрос и ответ
400	Неверно заданные параметры или другой неверный запрос

Коды состояния и ошибок помогают в устранении неполадок

Коды состояния и ошибок особенно полезны при устранения неполадок. Таким образом, можно рассматривать коды ошибок как дополнение к разделу по устранению неполадок.

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

В разделе по устранению неполадок можно перечислить сообщения об ошибках, связанных со следующими ситуациями:

текст ошибки должен точно документироваться, чтобы она легко появлялась при поиске.

Примеры кодов статусов и ошибок

Ниже приведены несколько вариантов разделов с кодами статусов и ошибок.

Context. io

Clearbit не только документирует стандартные коды состояния, но также описывает уникальные параметры, возвращаемые их API. Большинство разработчиков, вероятно, знакомы с кодами 200, 400 и 500, поэтому эти коды не требуют много пояснений. Но если API имеет уникальные коды, описывать их нужно адекватно и подробно.

Twitter

В Twitter не только описывается код и состояние, но также предоставляется полезная информация по устранению неполадок, потенциально помогая в устранении ошибок. Например, про ошибку 500 не просто сказано, что статус относится к неработающей службе, но и есть объяснение: «Обычно это временная ошибка, например, в ситуации высокой нагрузки или если у конечной точки временно возникают проблемы. Посетите форумы разработчиков на случай, если у других возникнут аналогичные проблемы, или повторите попытку позже».

Mailchimp

Mailchimp предоставляет удобочитаемые и понятные описания сообщений об ошибке. Например, в ошибке 403 вместо того, чтобы просто написать «Запрещено», Mailchimp объясняет причины, по которым можно получить ошибку запрещенного кода. У Mailchimp существует несколько типов ошибок 403. Запрос может быть запрещен из-за отключенной учетной записи пользователя или запроса, направленного не в тот центр обработки данных. В случае ошибки «WrongDataCenter» Mailchimp отмечает, что «она часто связана с неправильно настроенными библиотеками» и ссылается на дополнительную информацию о центрах обработки данных. Такой тип документации кода ошибки очень полезен для пользователей.

Flickr

В Flickr раздел «Коды ответов» встроен в описание каждой адресной темы API. Описания ошибок выглядят короткими. Хотя встраивание кодов ответов в каждую тему делает коды ошибок более заметными, в некоторых случаях такой подход менее полезен. Поскольку он встроен в каждую тему API, описания кодов ошибок должны быть краткими, иначе их содержимое будет перегружено информацией о запросе конечной точки.

Напротив, отдельная страница с перечнем кодов ошибок позволяет более подробно раскрывать каждый код, не вытесняя другую документацию. Отдельная страница также уменьшает избыточность и увеличивает объем информации.