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

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

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

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

Учитывайте каждое из следующих предложений по форматированию кода при настройке вашего руководства по стилю разработки Unity.

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

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

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

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

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

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

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

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

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

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

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

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

• Стиль Allman, также известный как стиль BSD (из BSD Unix), помещает открывающие фигурные скобки на новую строку.
• Стиль K&R, или "один истинный стиль скобок", сохраняет открывающую скобку на той же строке, что и предыдущий заголовок.

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

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

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

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

Не пропускайте скобки – даже для однострочных операторов. Скобки увеличивают согласованность, что делает ваш код более читаемым и поддерживаемым. В этом примере фигурные скобки четко отделяют действие, 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. Чистый код гораздо легче форматировать и рефакторить, если вы применяете эти советы по повышению продуктивности.

Чтобы настроить файл .editorconfig в Visual Studio Code, выполните следующие шаги:

• В корневом каталоге вашего проекта создайте новый файл с именем .editorconfig.
• Откройте файл .editorconfig и добавьте желаемые настройки конфигурации.

Вот пример конфигурации для C#:

# самый верхний файл EditorConfig

root = true

# Unix-стиль новых строк с новой строкой в конце каждого файла

[*]

end_of_line = lf

insert_final_newline = true

# 4 пробела для отступа

[*.cs]

indent_style = space

indent_size = 4

charset = utf-8

trim_trailing_whitespace = true

# Отступ с помощью табуляции для Makefiles

[Makefile]

indent_style = tab

# Специфические настройки для JSON файлов

[*.json]

indent_style = space

indent_size = 2