Лучшие практики форматирования для C# скриптов в Unity

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

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

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

Давайте рассмотрим некоторые рекомендации по форматированию.

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

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

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

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

Используйте свойства с телом выражения для однострочных, только для чтения свойств (=>): Это возвращает приватное резервное поле.

Все остальное использует синтаксис с телом выражения { get; set; } : Если вы просто хотите открыть публичное свойство, не указывая резервное поле, используйте авто-реализуемое свойство.

Примените синтаксис с телом выражения для аксессоров set и get. Не забудьте сделать «сеттер» приватным, если не хотите предоставлять доступ на запись. Выравнивайте закрывающую фигурную скобку с открывающей для многострочных блоков кода.

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

Сериализованные поля отображаются в Инспекторе, но вы не можете сериализовать статические, константные или только для чтения поля. Они должны быть либо публичными, либо помеченными атрибутом [SerializeField]. Unity сериализует только определенные типы полей, поэтому обратитесь к документации для полного набора правил сериализации.

Соблюдайте эти основные рекомендации при работе с сериализованными полями:

Используйте атрибут [SerializeField]: Атрибут SerializeField может работать с приватными или защищенными переменными, чтобы они отображались в Инспекторе. Это лучше инкапсулирует данные, чем пометка переменной как публичной, и предотвращает перезапись ее значений внешним объектом.

Используйте атрибут Range для установки минимальных и максимальных значений: Атрибут [Range(min, max)] удобен, если вы хотите ограничить то, что пользователь может назначить числовому полю. Он также удобно представляет поле в виде ползунка в Инспекторе.

Группируйте данные в сериализуемых классах или структурах, чтобы очистить Инспектор: Определите публичный класс или структуру и отметьте его атрибутом [Serializable]. Определите публичные переменные для каждого типа, который вы хотите сделать доступным в Инспекторе.

Ссылайтесь на этот сериализуемый класс из другого класса. Результирующие переменные появляются в сворачиваемых единицах в Инспекторе.

Существует два распространенных стиля отступов в C#:

Стиль Allman, также известный как стиль BSD (из BSD Unix), помещает открывающие фигурные скобки на новую строку.

Стиль K&R, или "один истинный стиль скобок", оставляет открывающую скобку на той же строке, что и предыдущий заголовок.

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

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

В Visual Studio для Windows перейдите в Инструменты > Параметры > Текстовый редактор > C# > Вкладки.

В Visual Studio для Mac перейдите в Настройки > Исходный код > Исходный код C#. Выберите Стиль текста, чтобы настроить параметры.

Примечание: Visual Studio предоставляет возможность преобразования вкладок в пробелы.

Не пропускайте скобки – даже для однострочных операторов. Скобки увеличивают согласованность, что делает ваш код более читаемым и поддерживаемым. В этом примере скобки четко отделяют действие DoSomething от цикла.

Если вам нужно будет добавить строку отладки или выполнить DoSomethingElse позже, скобки уже будут на месте. Сохранение условия на отдельной строке позволяет вам просто добавить точку останова.

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

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

Вот один пример отступа операторов case.

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

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

Используйте один пробел после запятой между аргументами функции.

Не добавляйте пробел после скобок и аргументов функции.

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

По возможности избегайте пробелов внутри скобок.

Используйте один пробел перед условиями управления потоком и добавьте пробел между оператором сравнения потока и скобками.

Используйте один пробел перед и после операторов сравнения.

Держите строки короткими и учитывайте горизонтальные пробелы. Определите стандартную ширину строки (80–120 символов) и разбивайте длинные строки на более мелкие выражения, а не позволяйте им переполняться.

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

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

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

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

• Группируйте зависимые или похожие методы вместе: Код должен быть логичным и последовательным. Держите методы, выполняющие одно и то же, рядом друг с другом, чтобы читателю вашей логики не приходилось прыгать по файлу.
• Используйте вертикальное пространство, чтобы отделить различные части вашего класса: Например, вы можете добавить две пустые строки между:
• Объявления переменных и методы
• Классы и интерфейсы
• блоки if-then-else (если это помогает читаемости)

Сведите это к минимуму, и если возможно, отслеживайте это в вашем руководстве по стилю.

Использование регионов в вашем коде

Директива #region позволяет вам сворачивать и скрывать секции кода в файлах C#, делая большие файлы более управляемыми и удобочитаемыми.

Тем не менее, если вы следуете общим рекомендациям по классам из этого руководства, размер вашего класса должен быть управляемым, а директива #region избыточной. Разбейте ваш код на более мелкие классы, вместо того чтобы скрывать блоки кода за регионами. Вы будете менее склонны добавлять регион, если исходный файл короткий.

Примечание. Многие разработчики считают регионы запахом кода или антипаттернами. Решите в команде, на какой стороне дебатов вы находитесь.

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

Чтобы настроить правила форматирования для редактора скриптов:

• В Visual Studio для Windows перейдите в Инструменты > Параметры, затем найдите Редактор текста > C# > Форматирование стиля кода.
• Используйте настройки для изменения параметров Общие, Отступ, Новые строки, Пробелы и Перенос.
• В Visual Studio для Mac выберите Visual Studio > Настройки, затем перейдите в Исходный код > Форматирование кода > Исходный код C#.
• Выберите Политику вверху, затем перейдите на вкладку Стиль текста. На вкладке C# Формат отрегулируйте настройки Отступ, Новые строки, Пробелы и Перенос.

Чтобы заставить ваш файл скрипта соответствовать стилевому руководству:

• В Visual Studio для Windows перейдите к сочетанию клавиш Правка > Дополнительно > Форматировать документ (Ctrl + K, Ctrl + D. Если вы хотите форматировать только пробелы и выравнивание табуляции, вы также можете использовать Запустить очистку кода (Ctrl + K, Ctrl + E) внизу редактора.
• В Visual Studio для Mac перейдите к Правка > Форматировать документ (Ctrl + I.

На Windows вы также можете поделиться настройками редактора из Инструменты > Импорт и экспорт настроек. Экспортируйте файл с форматированием кода C# по стилевому руководству, а затем пусть каждый член команды импортирует этот файл.

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

Примечание: Вы можете настроить файл EditorConfig (см. выше) вместо импорта и экспорта настроек Visual Studio. Это облегчает совместное использование форматирования между различными IDE. Это также имеет дополнительное преимущество работы с системой контроля версий. Смотрите .NET правила стиля кода для получения дополнительной информации.

Хотя это не специфично для чистого кода, обязательно ознакомьтесь с 10 способами ускорить ваш рабочий процесс программирования в Unity с Visual Studio. Помните, что форматировать и рефакторить чистый код удобнее, если вы применяете эти советы по повышению продуктивности.