Соглашения об именовании

Соглашения об именовании

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

Имена визуальных элементов используются для хранения ссылок на них в коде.

Универсального руководства по стилю не существует: выбирайте правила, которые лучше всего подходят вашей команде и проекту. Тем не менее обычно стоит придерживаться общепринятых отраслевых стандартов. Поэтому для визуальных элементов и таблиц стилей мы рекомендуем соглашение Block Element Modifier (BEM «блок, элемент, модификатор»). BEM широко применяется в CSS и современной веб-разработке, которые послужили источником идей для UI Toolkit.

По имени элемента, составленному в стиле BEM, можно сразу понять его назначение, расположение и связь с соседними элементами. В соглашении BEM используются три основных компонента: block-name__element-name--modifier-name Пример: navbar-menu__shop-button--small Каждая часть имени может содержать латинские буквы, цифры и дефисы. Части имени соединяются двойным подчёркиванием __ или двойным дефисом --. Рассмотрим все три компонента подробнее:

- Имя блока (block-name) обозначает высокоуровневый компонент: например, navbar-menu, панель характеристик персонажа или любой другой самостоятельный и значимый компонент интерфейса в макете. Для универсальной кнопки, не относящейся к конкретному блоку, имя блока можно опустить, например: button--small. - Элемент (element-name) является дочерней частью блока и поэтому семантически с ним связан. Иными словами, контекст элемента задаётся блоком, и без него элемент не существует. Например, shop-button оформлен иначе, чем другие кнопки блока navbar-menu; полное имя может выглядеть как navbar-menu__shop-button.

Если новый элемент создаёт дочерние элементы в конструкторе, назначьте им соответствующие классы. Например: my-block__first-child и my-block__other-child.

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

Дополнительные примеры имён в стиле BEM:

menu__button-home

menu__button-shop

navbar-menu__shop-button--small

navbar-menu__shop-button--large

Имена классов BEM описывают сами себя: разработчикам проще понять структуру и назначение компонентов и поддерживать ясную иерархию стилей по мере роста проекта. Общее правило - отдавайте предпочтение читаемости, а не краткости. Ясность важнее нескольких секунд, сэкономленных удалением пары гласных.

В этих примерах части имени разделяются дефисами (так называемый kebab-case) это распространённый стиль именования в CSS. Команде следует в начале проекта выбрать подходящую схему именования и придерживаться её на всём протяжении разработки. Подробнее о правилах именования CSS можно прочитать в этой статье и в документации UI Toolkit. Советы: соглашения об именовании в UI Toolkit Ниже приведены рекомендации по эффективному именованию:

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

- Подчёркивайте в именах роли и связи: например, используйте inventory__slot--equipped вместо inventory__button--equipped. Опускайте названия типов вроде Button и Label, если они не делают имя понятнее. - Избегайте имён и модификаторов, смысл которых может измениться. Например, пока цветовая схема не утверждена, используйте button--quit вместо button--red. Семантические имена предпочтительнее имён, описывающих внешний вид: они остаются актуальными после изменения оформления. - Распространите эти правила на графические ресурсы интерфейса UI Toolkit, например спрайты и текстуры. Единообразное именование в коде и ресурсах помогает сохранить понятные связи и порядок во всём проекте. - Если элемент планируется использовать в других проектах, добавьте к классам префикс, чтобы избежать конфликтов с существующими пользовательскими именами. Пространства имён и префиксы предотвращают коллизии при интеграции с другими проектами и библиотеками.

- Вызывайте AddToClassList() в конструкторе, чтобы назначать экземплярам элемента соответствующие классы USS. Метод добавляет необходимые классы при создании экземпляра, обеспечивая правильное применение стилей, единообразие и понятность кода интерфейса.

Создайте руководство по стилю C#

Если вы или ваша команда хотите усовершенствовать основные практики программирования и упростить масштабирование проекта, ознакомьтесь с нашей бесплатной электронной книгой «Создайте руководство по стилю C#: пишите более чистый и масштабируемый код». Используйте её, чтобы стандартизировать стиль кода и правила именования.

Скачать электронную книгу