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

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

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

• Улучшенная ремонтопригодность: Согласованное именование помогает поддерживать проект по мере его развития. Это упрощает такие задачи, как обновление функций или исправление ошибок.

• Облегчение совместной работы: Общая конвенция именования позволяет членам команды работать вместе более эффективно, поскольку они могут предвидеть, как будут названы и организованы объекты.

• Более легкое вхождение в команду: Новые члены команды могут быстрее войти в курс дела, если у них есть четкая и логичная система именования.

Когда вы добавляете объект (устройство, модель, переменную и т. д.), необходимо заполнить поле Name. Рекомендуется использовать стиль lowerCamelCase без пробелов в многословных названиях, начиная со строчной буквы и затем прописывая первую букву каждого последующего слова. Не ставьте пробелы между словами. Например:

• Имя контекста: monitoringMainPage, mqttDevice

• Имя функции: getUserInformation, xmlHttpRequest

• Имя переменной: inputData, unitsList

Нет необходимости указывать тип контекста в имени контекста. Тип контекста очевиден из группы контекста, а также отображается как часть контекстного пути контекста.

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

Поэтому используйте такие имена, как "highTemperature", и такие описания, как "High Temperature", вместо "highTemperatureAlert" и "High Temperature Alert".

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

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

Комментарии должны отражать суть действия, а не описывать каждую используемую операцию (например, почему используется именно эта операция, а не другая). Такой подход помогает достичь следующего:

• Комментарии не перегружены излишними деталями.

• Через комментарии можно понять назначение различных шагов, не читая их код

• Если часть функции набора правил нуждается в пересмотре, комментарии помогут быстро найти нужный шаг, не пересматривая каждый шаг по отдельности.

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

Вот несколько примеров описания и комментариев:

• Предположим, у нас есть функция, которая выводит информацию о пользователе, выбранном по входным параметрам. Мы можем назвать ее"getUserInformation" и указать в описании функции информацию типа "Получить информацию об указанном пользователе".

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

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

При разработке приложения очень важно, чтобы каждое имя точно отражало суть того, что оно представляет. Это не просто соблюдение стандартов разработки, а создание приложения, которое будет интуитивно понятным в обслуживании. Объекты в приложении часто упоминаются в процессе разработки. Например, когда вам нужно получить данные, хранящиеся в переменных, или манипулировать ими, наличие понятных имен позволяет быстро найти нужную переменную среди множества других.

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

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

Хорошая практика:

• monitoringMainPage - Четко указывает, что этот контекст относится к главной странице мониторинга.

• monitoringSettingPage - Указывает, что данный контекст связан с настройками в рамках мониторинга.

Плохая практика:

• monitoring - Это название слишком расплывчато и не дает информации о том, к какому аспекту мониторинга оно относится.

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

Хорошая практика:

• findUserByNameOrEmailF() - Указывает, что эта функция ищет пользователей либо по имени, либо по электронной почте.

• findUserByIdF() - Четко указывает, что эта функция ищет пользователей именно по их ID.

Плохая практика:

• findUserF1() - Не передает никакой информации о том, как работает этот поиск.

Для эффективного тестирования приложений рекомендуется использовать отдельные объекты(устройство, модель, переменная и т. д.), которые были специально созданы для этой цели. Чтобы облегчить идентификацию и последующую очистку этих тестовых артефактов в конце процесса разработки, рекомендуется добавлять к их описанию специальный префикс или постфикс, например "test". Примеры приведены ниже.

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

• Продублируйте этот шаг в наборе правил.

• Добавьте комментарий "test", чтобы указать, что на этом шаге используются тестовые данные.

• Замените исходное выражение на таблицу предопределенного формата, содержащую тестовые данные.

• Установите условие в исходном шаге на false.

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

Альтернативное решение вышеописанного сценария заключается в следующем:

• Клонируйте весь набор правил.

• Переименуйте исходный набор правил, добавив префикс "debugging".

• Добавьте "для тестирования" к описанию клонированного (тестового) набора правил.

• В новой тестовой версии замените все недоступные ресурсы константами или предопределенными тестовыми данными.

Когда отладка будет завершена:

• Найдите и удалите все наборы правил с пометкой "для тестирования".

• Вернитесь к использованию исходного набора правил (с префиксом "для отладки").

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

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

Функции и наборы правил в модели служат строительными блоками приложения, каждый из которых выполняет определенную задачу. Очень важно, чтобы их названия четко передавали их назначение, отвечая на вопрос "Что делает эта функция/набор правил?". Такая ясность в названиях облегчает понимание и использование в различных частях приложения. Начинать названия с глаголов не только позволяет сразу понять, какое действие они выполняют, но и помогает логически упорядочить их при сортировке в алфавитном порядке.

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

Дополнительные примеры, иллюстрирующие эффективное именование функций, включают:

• createSensor: Указывает на создание новой сущности датчика.

• getUserInformation: Указывает на получение информации о конкретном пользователе.

• sendAlertListByEmail: Четко указывает, что отправляет списки оповещений по электронной почте.