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

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

В 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#: пишите более чистый и масштабируемый код». Используйте её, чтобы стандартизировать стиль кода и правила именования.

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

Naming conventions

With UI Toolkit you’ll need to query the visual elements and USS using a string identifier, so using a defined set of standards will lead, overall, to fewer errors and more readable code. As dev teams will refer to the same UXML and USS assets that make up your interface, it’s important to standardize naming conventions for both visual elements and style sheets. Naming conventions help keep your hierarchy organized in UI Builder. It will also take out the guesswork of coding conventions and formatting conventions and help you have a consistent codebase.

The name of visual elements is used to store references to them in the code.

There is no one-size-fits-all style guide. Pick and choose what works best for your team and project. However, it’s generally recommended to stick as close to industry standards as possible. For that reason, we recommend the Block Element Modifier (BEM) naming convention for your visual elements and style sheets. BEM is widely used in the context of CSS and modern web development, from which UI Toolkit takes its inspiration.

At a glance, an element’s BEM-style name can tell you what it does, where it appears, and how it relates to other elements around it. BEM uses three main components in the following convention: block-name__element-name--modifier-name Here’s an example: navbar-menu__shop-button--small Each name part may consist of Latin letters, digits, and dashes. Also note that each name part is joined together with either a double underscore __ or a double dash --. Let’s look at the three components in detail: —

The block name (block-name) represents a high level-component, like a navbar-menu, character stats – any distinct and meaningful UI component in your layout. In the case of a generic button that is not specific to any particular block, that can simply be left out, e.g., button--small.

The element (element-name) is a child or part of a block and therefore semantically tied to its block. In other words elements rely on the block for their context and can’t exist without it. So, the example of shop-button indicates that this is styled differently from other buttons belonging to the navbar-menu block (e.g., shop-button in navbarmenu__shop-button). If your new element instantiates child elements in its constructor, assign the relevant classes to the children. For example, my-block__first-child, my-block__otherchild.

Finally, the modifier indicates a variation or state of a block or element. That could be when a button is pressed, a textbox item is selected and highlighted, or in our example, when it’s a small variant of the shop button. This makes it easy to adapt to different scenarios without duplicating code.

Here are some more examples of BEM naming: —

menu__button-home

menu__button-shop

navbar-menu__shop-button--small

navbar-menu__shop-button--large

BEM class names are self-descriptive, making it easier for developers to understand the structure and purpose of components and therefore, helping to maintain a clear hierarchy for managing and updating styles as projects grow. As a general rule of thumb, favor readability over brevity. Clarity is more important than any time saved from omitting a few vowels.

These examples use hyphen delimiting (aka Kebab case), which is common for CSS naming. Your team should decide early on in a project which naming scheme works best for them and stick to it throughout development. Read more about CSS naming conventions in this article, as well as in the UI Toolkit documentation. Tips: Naming conventions in UI Toolkit Here are some guidelines for effective naming: —

Keep names short and clear (unambiguous). Ensure that names are concise yet descriptive enough to convey their purpose and role within the UI.

Use names to emphasize roles and relationships, such as inventory__slot-equipped instead of inventory__button--equipped. Omit Type names like Button or Label if they don’t add clarity.

Avoid names/modifiers that can change (e.g., use "button–quit" instead of "button– red" when the color scheme is not yet final). Use semantic naming rather than presentational naming, which ensures names remain relevant even if styling details change.

Extend these conventions to art assets, like sprites and textures associated with the UI Toolkit interface. Consistency in naming between code and assets helps maintain a clear relationship and better organization throughout the project.

If you use the element in other projects, consider prefixing your classes to avoid conflicts with existing user class names. Namespacing or prefixing can prevent clashes when integrating with other projects or libraries.

Use AddToClassList() in the constructor to add the relevant USS classes to your element instances. This method ensures that the appropriate styles are applied by adding the necessary classes at the time of element instantiation, maintaining consistency and clarity in your UI code.

Create a C# style guide If you or your team wants to refine key coding practices to make your project more scalable, check out our free e-book, Create a C# style guide: Write cleaner code that scales. Use this guide as needed to help standardize your code style and naming conventions.

Download the e-book