Это руководство поможет вам интегрировать StyleCop в рабочий процесс Unity. Он написан с предположением, что вы имеете некоторое представление о соглашениях о стилях кодирования и о том, почему для команды важно согласовать единый стиль. Если вы еще не согласны с этой идеей, я бы порекомендовал это введение в стили кода, или нашу предыдущую историю о нашем решении принять StyleCop.
Мы расскажем, что такое StyleCop и как запустить его с Unity как на Windows, так и на Mac. Мы также объясним, как мы игнорируем определенные файлы, чтобы проверять только соответствующие файлы проекта, что важно для проектов Unity со сторонними ресурсами.
Обновление (январь 2019 г.). Мы прекратили использование StyleCop по нескольким причинам. Основная причина в том, что мы перешли на VSCode на Mac, который в настоящее время не поддерживает StyleCop. Мы по-прежнему выступаем за проверку стиля, но, к сожалению, в настоящее время не знаем бесплатного варианта, который работал бы на всех платформах и IDE. Сообщите нам ниже, если у вас есть решение!
Что такое StyleCop?
StyleCop - это инструмент статического анализа кода с открытым исходным кодом, работающий в Visual Studio и проверяющий нарушения стиля кода. Правила по умолчанию были установлены путем объединения предпочтений различных команд в Microsoft и призваны подчеркнуть удобочитаемость и ремонтопригодность кода C #, но пользователи также могут настраивать свои собственные правила.
Мы используем StyleCop как на Windows, так и на Mac, используя Visual Studio и MonoDevelop. Мы запускаем его (к сожалению, вручную) перед фиксацией кода, чтобы убедиться, что наша кодовая база соответствует требованиям.
Установка
Visual Studio
Для установки в Visual Studio просто скачайте установщик StyleCop. После этого в вашей Visual Studio должна появиться новая команда в меню Инструменты.
Обновление. Если вы используете NuGet Package Manager и Visual Studio 2017, вам следует обратиться к решению Джона Вандербека на форуме Unity Answers.
MonoDevelop
Вам нужно будет загрузить надстройку, чтобы StyleCop работал с MonoDevelop.
- Загрузите надстройку для своей версии MonoDevelop. В настоящее время Unity поставляется с 5.x.
- Открыть MonoDevelop
- Перейдите в MonoDevelop-Unity - ›Менеджер надстроек
- Нажмите Установить из файла… и выберите файл .mpack.
Visual Studio Community 2017 для Mac
Сообщество Visual Studio для Mac, как и MonoDevelop, основано на Xamarian Studio. Поэтому процесс установки идентичен MonoDevelop, за исключением того, что вместо открытия диспетчера надстроек вам нужно использовать диспетчер расширений, который можно найти в разделе Сообщество Visual Studio - ›Расширения.
Выполнить StyleCop
Теперь у вас должна быть возможность запускать StyleCop из меню «Инструменты» как для отдельных файлов, так и для всего проекта. Если вы сделаете это в существующем проекте, вы можете увидеть, что StyleCop вернет 1000+ предупреждений. Обратите внимание, что он прерывает процесс после 1000 нарушений, поэтому, вероятно, будет больше предупреждений. Не волнуйтесь, мы заставим StyleCop игнорировать некоторые из этих файлов позже.
Настройте свои правила
Если стандартные правила StyleCop вам не подходят, вы можете отключить многие из них или даже создать свои собственные. Правила можно настроить для каждого проекта отдельно или глобально для нескольких проектов. Их даже можно применять каскадно с несколькими файлами настроек для одного проекта. Концепция каскадирования работает следующим образом:
- Файл глобальных настроек в папке установки StyleCop - это настройки по умолчанию для всех проектов.
- Файлы настроек уровня проекта находятся в каждом проекте и имеют приоритет над глобальными настройками.
- Любые дополнительные файлы настроек в проекте переопределят ваши настройки проекта.
Для простоты в нашем проекте мы используем только один файл настроек, который находится в корневой папке и проверяется в системе контроля версий. Я замалчил многие детали, поэтому, если вам нужно что-то более сложное, вам следует обратиться к документации.
Настроить правила проекта
В окне решения вашей среды IDE вы сможете открыть меню параметров для сборки решения. В Visual Studio это меню появляется, когда вы щелкаете правой кнопкой мыши сборку вашего проекта (не щелкайте правой кнопкой мыши решение). В этом меню параметров должен быть пункт меню Настройки StyleCop. После выбора этого файла в корневой папке вашего проекта будет создан файл с именем Settings.Stylecop.
Примечание. У нас возникают проблемы с просмотром окна настроек в MonoDevelop для Mac, вероятно, из-за некоторых проблем с нашей установкой X11. Чтобы обойти эту проблему, мы создали файл настроек в Windows и Visual Studio.
Если вы работаете в Windows, файл Settings.StyleCop можно открыть из проводника и отредактировать через графический интерфейс. Если это не помогло, попробуйте перетащить файл настроек в приложение под названием StyleCopSettingsEditor.exe, которое установлено в папке с файлами программы StyleCop.
В графическом интерфейсе вы можете включать и выключать любые правила, которые вам нравятся, и повторно запускать StyleCop, чтобы убедиться, что они действуют. Обратите внимание, что полужирный элементы в графическом интерфейсе выше - это те правила, которые имеют приоритет над глобальными настройками.
Мы рекомендуем проверить файл Settings.StyleCop в вашей системе контроля версий, чтобы у всех членов вашей команды были одинаковые правила.
Наши индивидуальные правила
Мы внесли лишь несколько изменений в правила по умолчанию. Мы оценили, какие правила не нужны из-за фреймворка Unity или нашего рабочего процесса.
- Отключены все правила заголовка файла
- Установите для параметра "Игнорировать частные поля" значение True.
- Установите для параметра "Включить поля" значение False
- Добавлен список RecognizedWords для словаря, но с тех пор мы отключили эту функцию
- Отключена проверка орфографии в документации из-за того, что она не работает в настройке Mac.
Мы отключаем проверку комментариев к частным полям, потому что мы используем всплывающие подсказки для всего, что доступно в Unity. Возможно, мы могли бы сделать это специальным правилом в StyleCop, чтобы проверить его, но это кажется излишним.
[Tooltip(“The maximum number of hits the projectile can make against the ground before dying.”)] [SerializeField] private int maxNumGroundHits;
Вы можете найти наш файл Settings.StyleCop на GitHub вместе с простым примером.
Игнорировать файлы
При работе с проектами Unity практически невозможно использовать StyleCop без возможности игнорировать импортированные сторонние ресурсы. Немногие сторонние активы соответствуют StyleCop, и даже те, которые соответствуют, не будут соответствовать вашим индивидуальным правилам. Поэтому нам нужно заставить StyleCop игнорировать определенные файлы. Предположительно существует много способов сделать это, но мы смогли найти только один метод, который работает на всех платформах.
Чтобы игнорировать эти файлы, мы добавляем элемент Parser в XML настроек. В этом элементе мы перечисляем шаблоны имен файлов для исключения из нашей проверки StyleCop. Эти имена файлов могут быть регулярными выражениями, поэтому вы можете делать гораздо больше интересных вещей, чем мы сделали ниже.
Было бы утомительно добавлять каждый отдельный файл стороннего скрипта вручную, поэтому мы создали инструмент Unity Editor, чтобы ускорить этот процесс и управлять им.
Игнорировать файлы в Unity
Кевин Маби создал эту Утилиту игнорирования StyleCop, чтобы мы могли массово игнорировать файлы с помощью анализатора, описанного выше. Каждый раз, когда мы импортируем новый актив, мы также игнорируем все его скрипты, проверяя папку для импортированного актива.
Утилита с открытым исходным кодом, поэтому вы можете использовать ее в своих проектах. Вы найдете инструкции и дополнительную информацию на нашей странице проекта Github.
Отказ от ответственности и ограничения
Для некоторых StyleCop слишком обременительна, чтобы иметь с ней дело. Но из-за отсутствия лучшего (бесплатного) инструмента мы считаем, что стоит приложить дополнительные усилия, чтобы поддерживать наш код в долгосрочной перспективе. Тем не менее, у StyleCop есть свои ненавистники.
Хотя средства проверки стиля являются важными инструментами для команды инженеров, мы обнаружили некоторые ограничения в нашей способности полностью интегрировать StyleCop в наши многоплатформенные процессы разработки и непрерывной интеграции. Если вам удалось решить любую из этих проблем, я буду рад получить известие от вас.
- Сам StyleCop не решает никаких проблем автоматически. StyleFix (бесплатно) - это опция для автоматического запуска исправлений StyleCop, но мы ее не использовали.
- JetBrains Resharper может быть более надежным инструментом, если вы можете себе это позволить. CodeMaid (бесплатно) и JustCode могут автоматически исправлять проблемы и, по крайней мере, частично покрывать жалобы StyleCop, если вам нужно более легкое решение.
- StyleCop выдает не самые дружелюбные ошибки; вы можете некоторое время гуглить предупреждающие сообщения типа закрывающая скобка расставлена неправильно », пока не выясните, что они на самом деле означают.
- По моему опыту, текущую документацию найти сложно, отчасти поэтому и пишется эта статья.
- Иногда может казаться, что принципы Unity и StyleCop противоречат друг другу.
- Запуск его в Mac OS и MonoDevelop не был гладким процессом.
Чего не хватает в нашем рабочем процессе
Мы еще не смогли полностью интегрировать StyleCop в наш процесс непрерывной интеграции. Без официальных инструментов командной строки мы не смогли бы запустить его в наших хуках git, которые были бы жизнеспособным местом, по крайней мере, для предотвращения отправки несовместимого кода. У нас также нет StyleCop, который запускается автоматически во время сборки, хотя это может быть возможно более талантливым программистом Unity, чем я. В конечном счете, мы полагаемся на публичное осуждение всякий раз, когда кто-либо нарушает код, и по большей части это приемлемо.
Вывод
Что ж, я должен признать, что этот урок ушел от меня. Я надеюсь, что вы смогли уследить за ним и извлекли пользу из StyleCop. Если у вас есть какие-либо вопросы или комментарии, свяжитесь с нами. Нам нравится получать известия от других разработчиков.
