Наведите порядок в своем коде: Как создать свой собственный стиль кода C#
Хотя существует более одного способа форматирования кода Unity C#, согласование единого стиля кода для Вашего проекта позволит Вашей команде создать чистую, читаемую и масштабируемую кодовую базу. В этом блоге мы приводим некоторые рекомендации и примеры, которые Вы можете использовать для разработки и поддержания собственного руководства по стилю кода.
Обратите внимание, что это лишь рекомендации, основанные на данных, предоставленных компанией Microsoft. Это Ваш шанс вдохновиться и решить, что лучше всего подходит для Вашей команды.
В идеале, проект Unity должен ощущаться так, будто его разрабатывал один автор, независимо от того, сколько разработчиков на самом деле над ним трудится. Руководство по стилю поможет унифицировать Ваш подход к созданию более целостной кодовой базы.
Хорошая идея - следовать отраслевым стандартам, где это возможно, и просматривать существующие руководства по стилю в качестве отправной точки для создания своего собственного. В сотрудничестве с внутренними и внешними экспертами Unity мы выпустили новую электронную книгу, Создайте руководство по стилю C#: Пишите более чистый код, который масштабируется для вдохновения, основываясь на всеобъемлющем стиле C# от Microsoft.
Руководство по стилю Google C# - еще один замечательный ресурс для определения рекомендаций по именованию, форматированию и комментированию. Опять же, не существует правильного или неправильного метода, но мы решили следовать стандартам Microsoft для нашего собственного руководства.
Наша электронная книга, а также пример файла на C# доступны бесплатно. Оба ресурса посвящены наиболее распространенным соглашениям по кодированию, с которыми Вы столкнетесь при разработке в Unity. Все это, по сути, подмножество рекомендаций по проектированию Microsoft Framework Design, которые включают в себя огромное количество лучших практик, выходящих за рамки того, что мы рассматриваем в этом посте.
Мы рекомендуем адаптировать рекомендации, представленные в нашем руководстве по стилю, в соответствии с предпочтениями Вашей команды. Эти предпочтения должны быть приоритетнее наших предложений и рекомендаций Microsoft Framework Design, если они противоречат друг другу.
Разработка руководства по стилю требует предварительных инвестиций, но впоследствии принесет свои дивиденды. Например, управление единым набором стандартов может сократить время, которое разработчики тратят на перестройку, если они переходят в другой проект.
Конечно, последовательность - это ключевой момент. Если Вы последуете этим рекомендациям и в будущем Вам понадобится изменить руководство по стилю, несколько операций поиска и замены помогут быстро перенести Вашу кодовую базу.
Сосредоточьтесь на создании прагматичного руководства по стилю, которое будет соответствовать Вашим потребностям и охватывать большинство повседневных случаев использования. Не перегружайте его, пытаясь с самого начала учесть все возможные варианты. Руководство будет органично развиваться с течением времени, по мере того как Ваша команда будет итерировать его от проекта к проекту.
Большинство руководств по стилю включают в себя основные правила форматирования. Между тем, конкретные соглашения об именовании, политика использования пространств имен и стратегии для классов - это несколько абстрактные области, которые могут быть усовершенствованы с течением времени.
Давайте рассмотрим некоторые общие соглашения по форматированию и наименованиям, которые Вы можете рассмотреть для своего руководства по стилю.
Два распространенных стиля отступа в C# - это стиль Allman, который помещает открывающие фигурные скобки на новую строку (также известный как стиль BSD из BSD Unix), и стиль K&R, или "стиль одной истинной скобки", который сохраняет открывающую скобку на той же строке, что и предыдущий заголовок.
Стремясь улучшить читабельность, мы выбрали для нашего руководства стиль Allman, основанный на рекомендациях Microsoft Framework Design:
// EXAMPLE: Allman or BSD style puts opening brace on a new line.
void DisplayMouseCursor(bool showMouse)
{
if (!showMouse)
{
Cursor.lockState = CursorLockMode.Locked;
Cursor.visible = false;
}
}
// EXAMPLE: K&R style puts opening brace on the previous line.
void DisplayMouseCursor(bool showMouse){
if (!showMouse) {
Cursor.lockState = CursorLockMode.Locked;
Cursor.visible = false;
}
}Какой бы стиль Вы ни выбрали, убедитесь, что каждый программист в Вашей команде следует ему.
В руководстве также должно быть указано, следует ли включать скобки во вложенные многострочные утверждения. Хотя удаление скобок в следующем примере не приведет к ошибке, это может запутать читателя. Вот почему наш гид рекомендует использовать брекеты для четкости, даже если они необязательны.
// EXAMPLE: Keep braces for clarity.
for (int i = 0; i < 10; i++)
{
for (int j = 0; j < 10; j++)
{
ExampleAction();
}
}
// AVOID: Removing braces from nested multiline statements
for (int i = 0; i < 10; i++)
for (int j = 0; j < 10; j++)
ExampleAction();Такая простая вещь, как горизонтальный интервал, может улучшить внешний вид Вашего кода на экране. Хотя Ваши личные предпочтения в форматировании могут варьироваться, вот несколько рекомендаций из нашего руководства по стилю для улучшения общей читабельности:
- Добавьте пробелы, чтобы уменьшить плотность кода:Дополнительные пробелы могут создать ощущение визуального разделения между частями строки
// EXAMPLE: Add spaces to make lines easier to read.
for (int i = 0; i < 100; i++) { DoSomething(i); }
// AVOID: No spaces
for(int i=0;i<100;i++){DoSomething(i);}- Используйте одинарный пробел после запятой между аргументами функции.
// EXAMPLE: Single space after comma between arguments
CollectItem(myObject, 0, 1);
// AVOID:
CollectItem(myObject,0,1);- Не добавляйте пробел после скобок и аргументов функции.
// EXAMPLE: No space after the parenthesis and function arguments
DropPowerUp(myPrefab, 0, 1);
// AVOID:
DropPowerUp( myPrefab, 0, 1 );- Не используйте пробелы между именем функции и круглыми скобками.
// EXAMPLE: Omit spaces between a function name and parenthesis.
DoSomething()
// AVOID:
DoSomething ()- Избегайте пробелов внутри скобок.
// EXAMPLE: Omit spaces inside brackets.
x = dataArray[index];
// AVOID:
x = dataArray[ index ];- Используйте одинарный пробел перед условиями управления потоком: Добавьте пробел между оператором сравнения потоков и круглыми скобками.
// EXAMPLE: Space before condition; separate parentheses with a space
while (x == y)
// AVOID:
while(x==y)- Используйте одинарный пробел перед и после операторов сравнения.
// EXAMPLE: Space before condition; separate parentheses with a space
while (x == y)
// AVOID:
while(x==y)Переменные обычно представляют собой состояние, поэтому старайтесь приписывать к их именам понятные и описательные существительные. Вы можете использовать префикс booleans с глаголом для переменных, которые должны указывать на истинное или ложное значение. Часто они являются ответом на такой вопрос, как, например, бежит ли игрок? Игра окончена? Приправьте их глаголом, чтобы уточнить их значение. Часто это сопряжено с описанием или условием, например, isPlayerDead, isWalking, hasDamageMultiplier и т.д.
Поскольку методы выполняют действия, хорошее правило - начинать их названия с глагола и добавлять контекст по мере необходимости, например, GetDirection, FindTarget и так далее, в зависимости от возвращаемого типа. Если метод имеет возвращаемый тип bool, его также можно сформулировать в виде вопроса.
Как и в случае с булевыми переменными, добавьте к методам глагол, если они возвращают условие "правда-ложь". Это формулирует их в виде вопроса, например, IsGameOver, HasStartedTurn.
Существует несколько соглашений для именования событий и обработчиков событий. В нашем руководстве по стилю мы называем событие с помощью глагольной фразы, подобно методу. Выберите название, которое точно передает изменение состояния. Используйте причастие настоящего или прошедшего времени, чтобы указать на события "до" или "после". Например, укажите OpeningDoor для события перед открытием двери и DoorOpened для события после.
Мы также рекомендуем Вам не сокращать имена. Хотя экономия нескольких персонажей может показаться выгодной в краткосрочной перспективе, то, что очевидно для Вас сейчас, может не быть таковым через год для другого члена команды. Имена Ваших переменных должны раскрывать их смысл и быть легко произносимыми. Переменные с одной буквой подходят для циклов и математических выражений, но в остальном Вам следует избегать сокращений. Ясность важнее, чем время, сэкономленное на опускании нескольких гласных.
В то же время, используйте одно объявление переменной на строку; это менее компактно, но также менее подвержено ошибкам и улучшает читаемость. Избегайте лишних названий. Если Ваш класс называется Player, Вам не нужно создавать переменные-члены PlayerScore или PlayerTarget. Обрежьте их до уровня Score или Target.
Кроме того, избегайте слишком большого количества префиксов или специальных кодировок. В нашем руководстве мы рекомендуем использовать префикс частных переменных-членов с подчеркиванием (_), чтобы отличить их от локальных переменных. В некоторых руководствах по стилю используются префиксы для закрытых переменных-членов (m_), констант (k_) или статических переменных (s_), так что имя раскрывает больше информации о переменной.
Тем не менее, хорошей практикой является префикс названий интерфейсов с большой буквы "I", а затем прилагательное, описывающее функциональность. Вы можете даже приписать к методу поднятия события (в теме) слово "On": Субъект, вызывающий событие, обычно делает это из метода с префиксом "On", например, OnOpeningDoor или OnDoorOpened.
// EXAMPLE: Prefix interface names with a capital “I”
public interface IDamageable<T>
{
void Damage(T damageTaken);
}
// EXAMPLE: Raising an event if you have subscribers
public void OnDoorOpened()
{
DoorOpened?.Invoke();
}Регистр Camel и регистр Pascal являются общепринятыми стандартами, по сравнению с регистром Snake или Kebab, или венгерскими обозначениями. Наше руководство рекомендует использовать регистр Pascal для публичных полей, перечислений, классов и методов, и регистр Camel для приватных переменных, поскольку это является общепринятой практикой в Unity.
Существует множество дополнительных правил, которые необходимо учитывать, помимо тех, что описаны здесь. Руководство по примерам и наша новая электронная книга, Создайте руководство по стилю C#: Пишите более чистый код, который масштабируется, дайте множество других советов для лучшей организации.
Концепция чистого кода направлена на то, чтобы сделать разработку более масштабируемой за счет соответствия набору производственных стандартов. Руководство по стилю должно устранить большую часть догадок разработчиков о том, каких условностей им следует придерживаться. В конечном итоге, это руководство должно помочь Вашей команде прийти к консенсусу вокруг Вашей кодовой базы, чтобы развить Ваш проект до коммерческого производства.
Насколько полным должно быть Ваше руководство по стилю, зависит от Вашей ситуации. Ваша команда сама решает, хотят ли они, чтобы их руководство устанавливало правила для более абстрактных, неосязаемых понятий. Сюда могут входить правила использования пространств имен, разбиения классов на классы или применения таких директив, как директива #region (или нет). Хотя #region может помочь Вам сворачивать и скрывать участки кода в файлах C#, делая большие файлы более управляемыми, это также пример того, что многие разработчики считают запахами кода или антипаттернами. Поэтому Вам лучше не устанавливать строгих стандартов для этих аспектов стилизации кода. Не все должно быть изложено в руководстве - иногда достаточно просто обсудить и принять решение всей командой.
Когда мы беседовали с экспертами, помогавшими в создании нашего руководства, их главным советом была читабельность кода. Вот несколько советов о том, как этого добиться:
- Используйте меньше аргументов: Аргументы могут увеличить сложность Вашего метода. Сократив их количество, Вы облегчаете чтение и тестирование методов.
- Избегайте чрезмерной перегрузки: Вы можете создавать бесконечные перестановки перегрузок методов. Выберите несколько, которые отражают то, как Вы будете вызывать метод, а затем реализуйте их. Если Вы все же перегружаете метод, предотвратите путаницу, убедившись, что каждая сигнатура метода имеет определенное количество аргументов.
- Избегайте побочных эффектов: Метод должен делать только то, что указано в его названии. Избегайте изменения чего-либо, выходящего за его пределы. По возможности передавайте аргументы по значению, а не по ссылке. Поэтому, отправляя результаты по ключевому слову out или ref, убедитесь, что это именно то, что Вы хотите сделать с помощью данного метода. Хотя побочные эффекты полезны для решения определенных задач, они могут привести к непредвиденным последствиям. Напишите метод без побочных эффектов, чтобы снизить вероятность неожиданного поведения.
Мы надеемся, что этот блог поможет Вам начать разработку собственного руководства по стилю. Узнайте больше из нашего примера на C# и совершенно новой электронной книги, в которой Вы можете просмотреть предложенные нами правила и настроить их в соответствии с предпочтениями Вашей команды.
Конкретные правила не так важны, как то, что все согласны неуклонно следовать им. Если Вы сомневаетесь, полагайтесь на собственное развивающееся руководство Вашей команды, чтобы разрешить любые разногласия по поводу стиля. В конце концов, это групповая работа.
