Читабельність коду

Читабельність коду — важливий аспект розробки додатків, який часто ігнорується. Читабельний код легше розуміти, підтримувати та налагоджувати.

Правила іменування

Послідовні конвенції найменування значно покращують читабельність вашого коду. Це допомагає швидко визначити призначення кожного елемента у вашому додатку та полегшує орієнтацію у вашій кодовій базі.

Загальні правила іменування

У цьому розділі описано правила іменування «верблюжий випадок» та «випадок Паскаля». Якщо ви вже знайомі з цими термінами, ви можете пропустити вперед.

Чохол для верблюда

Використовуйте Camel Case для контролю та змінних. Регістр верблюда починається з префікса нижнього регістру, видаляє всі пробіли з назв об’єктів або змінних і пише з великої літери першу літеру кожного слова після першого. Наприклад, елемент керування введенням тексту може мати назву txtUserEmailAddress.

Відмінок Паскаля

Використовуйте корпус Pascal для джерел даних. Випадок Паскаля іноді називають «верхньою верблюжою справою». Як і верблюжий відмінок, він видаляє всі пробіли і пише першу букву слів з великої літери. Однак, на відміну від верблюжого відмінка, відмінок Паскаля також пишеться з великої літери перше слово. Наприклад, поширеним джерелом даних у Power Apps є роз'єм Microsoft Office 365 Users, який у коді називається Office365Users.

Псевдоніми

Обирайте імена екранів, які чітко показують призначення екрану, що полегшує навігацію по складних додатках у Power Apps Studio.

Екранні читачі читають вголос імена екранів. Користувачі з потребами у доступності зору покладаються на ці екранні читачі. Використовуйте просту мову для іменів користувача, додавайте пробіли та уникайте скорочень. Завершуйте кожне ім'я словом «Екран», щоб надати чіткий контекст при оголошенні назви.

Ось кілька хороших прикладів:

  • Home_Screen або Home Screen
  • Search_Screen або Search Screen

Скріншот, який показує список імен екранів, що відповідають описаній схемі.

Ці приклади імен користувачів менш зрозумілі:

  • Home
  • LoaderScreen
  • EmpProfDetails
  • Thrive Help

Імена елементів керування

Використовуйте корпус верблюда для всіх імен контролів на полотні. Почніть з опису з трьох символів, а потім з метою керування. Такий підхід допомагає визначити тип елемента керування та полегшує побудову формул та пошук. Наприклад, вказує, lblUserName що елементом керування є мітка.

У наведеній нижче таблиці наведено абревіатури для загальних елементів керування.

Ім’я елемента керування Абревіатура
Емблема БДГ
Кнопка btn
Керування камерою Камера
Полотно Можете
Картка ЦП
Діаграми ХР
Прапорець ЧК
Колекція пол
Поле зі списком CMB
Компонент Проект
Контейнер Проти.
Дати ДТЕ
Розкривний список ДРП
Форма frm
Галерея Гал
Групувати ВРП
Заголовок Роздільна здатність HDR
Текст у форматі HTML HTM
Піктограма ICO
Зображення img
Кнопка «Інформація» відомості
Мітка фунтів стерлінгів
"Зв’язати" ЛНК
Список Лст
Мікрофон мікрофон
Microsoft Stream Вул
Форма розділу сторінки с.
Введення пером перо
Плитка Power BI ПБІ
Індикатор перебігу виконання ПБАР
Оцінка РТГ
Редактор форматованого тексту РТЕ
Фігури (прямокутник, коло і так далі) ШП
Повзунок СЛД
Список вкладок вказівник
Table ТБЛ
Введення тексту txt
Таймер TMR
Кнопка-перемикач ТГЛ
Відео від

Детальний перелік елементів керування та їх властивості описані в Довіднику елементів керування.

Примітка

Імена елементів керування мають бути унікальними для всієї програми. Якщо елемент керування використовується повторно на кількох екранах, коротке ім’я екрана має містити суфікс. Наприклад galBottomNavMenuHS, де "HS" означає "Головний екран". Такий підхід полегшує посилання на елемент керування у формулах на різних екранах.

Ось кілька поганих прикладів:

  • zipcode
  • Next

Коли ви послідовно називаєте елементи керування, ваша програма стає чистішою в режимі навігації, а код також чистішим.

Скріншот навігаційного вигляду, що показує назви елементів за описаним шаблоном.

Назви джерел даних

Коли ви додаєте джерело даних до свого додатку, ви не можете змінити назву в додатку Power Apps. Ім’я успадковується від вихідного з’єднувача або сутностей даних, які є похідними від з’єднання.

Ось кілька прикладів:

  • ім'я успадковане від вихідного роз'єму: У вашому коді роз'єм користувача Office 365 має назву Office365Users.
  • Сутності даних, отримані з з'єднання: Список Microsoft SharePoint з назвою Employees повертається з SharePoint роз'єму. Отже, назва джерела даних у вашому коді — Employees. Той самий додаток Power Apps також може використовувати той самий конектор SharePoint для access списку SharePoint під назвою Contractors. У цьому випадку ім’я джерела даних у коді таке Contractors.

Дізнайтеся більше про роз'єми та з'єднання в розділі «Огляд роз'ємів для додатків Canvas».

З’єднувачі стандартної дії

У стандартних екшн-конекторах, які відкривають функції, таких як LinkedIn, ім'я джерела даних і його операції використовують корпус Pascal. Наприклад, LinkedIn джерело даних має назву LinkedIn і має операцію під назвою ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Настроювані з’єднувачі

Використовуйте власні конектори для підключення до інтерфейсів програмування застосунків (API), таких як сервіси або бізнес-API, створені вашою компанією. Будь-який виробник у вашому оточенні може створити власні роз'єми. Використовуйте корпус Pascal для назви джерела даних та його операцій. Назва власного роз'єму та спосіб його появи в Power Apps можуть відрізнятися.

Розглянемо цей приклад спеціального з’єднувача з іменем MS Auction Item Bid API.

Скріншот конектора під назвою MS Auction Item Bid API (API для ставок на предмети).

Коли ви створюєте з'єднання з цього конектора і додаєте його до Power Apps додатку як джерело даних, воно з'являється як AuctionItemBidAPI.

Скріншот конектора, який показує, що назва — AuctionItemBidAPI.

Щоб дізнатися причину, пошукайте в файлі OpenAPI атрибут титулу, який містить текст Auction Item Bid API.

"info": {
    "version": "v1",
    "title": "Auction Item Bid API"
},

Power Apps видаляє всі пробіли з цього значення атрибута і використовує його як назву вашого джерела даних.

Порада

Змініть значення цього атрибуту на ім'я з паскальним корпусом, наприклад, AuctionItemBidAPI і використовуйте його як ім'я вашого власного з'єднання. Так не буде плутанини. Змініть це значення перед імпортом файлу OpenAPI , щоб створити власний з’єднувач.

Примітка

Якщо ви використовуєте опцію Create from blank замість імпорту існуючого файлу OpenAPI, Power Apps запитує ім'я власного конектора. Це ім'я є і назвою користувацького конектора, і значенням атрибута title всередині файлу OpenAPI. Використовуйте назву з паскальним корпусом, щоб AuctionItemBidAPI усе було послідовно і просто.

Таблиці даних Excel

Power Apps використовує DataTables у Microsoft Excel для підключення до даних у робочих аркушах Excel. Враховуйте ці моменти під час створення документів Excel як джерел даних:

  • Надайте своїм DataTables описові назви. Ім'я є в додатку Power Apps, коли ви пишете код для підключення до нього.
  • Використовуйте одну таблицю даних на аркуші.
  • Дайте однакове ім’я DataTable і аркушу.
  • Використовуйте описові назви стовпців у таблицях даних.
  • Використовуйте корпус Pascal. Кожне слово назви DataTable має починатися з великої літери, наприклад EmployeeLeaveRequests.

Назви змінних

Іменування змінних у додатках Canvas важливі для підтримки читабельності, узгодженості та clarity у ваших проєктах Power Apps. Хоча суворий стандарт не дотримується, узгоджені правила іменування в усьому додатку canvas можуть полегшити вам та іншим співавторам розуміння, використання та керування змінними.

  • Використовуйте верблюжий відмінок, коли перша літера кожного слова пишеться з великої літери, крім першого слова.
  • Вибирайте значущі та описові назви, які чітко описують призначення або зміст змінної. Уникайте надто загальних назв, таких як temp або var1. Натомість використовуйте описові назви на кшталт userEmail або totalAmount.
  • Розгляньте можливість використання префіксів або суфіксів для позначення типу змінної. Наприклад:
    • strUserName для змінної text/string
    • numTotalAmount для числової змінної
    • boolIsEnabled для булевої змінної
    • locVarName для локальних змінних/контекстних змінних
    • gblVarLoginUser для глобальних змінних
  • Вирішіть, чи слід називати ваші змінні у формі однини чи множини, і дотримуйтесь цієї угоди. Наприклад, послідовно використовувати userCount або users.
  • Уникайте використання зарезервованих слів або імен, які можуть суперечити функціям або ключовим словам Power Apps. Перевірте документацію Power Apps для списку зарезервованих слів.
  • Розгляньте можливість використання префіксів, які надають контекст про використання змінної або область видимості. Наприклад:
    • frm для змінних форми
    • col для колекцій
    • var для змінних загального призначення
  • Уникайте спеціальних символів. Тримайте імена в буквено-цифровому стилі та уникайте спеціальних символів або пробілів. Дотримуйтесь букв і цифр.

Power Apps дозволяє контекстним і глобальним змінним мати однакові назви. Таке поширення може спричинити плутанину, оскільки ваші формули за замовчуванням використовують контекстні змінні, якщо ви не використовуєте оператор роз'яснення.

Щоб уникнути цієї ситуації, дотримуйтесь таких умовних позначень:

  • Додайте префікс контекстних змінних за допомогою loc.
  • Додайте до глобальних змінних префікс з gbl.
  • Назва після префікса має вказувати на намір або призначення змінної. Ви можете використовувати кілька слів, не розділяючи їх спеціальними символами, наприклад, підкресленнями, якщо пишете першу літеру з великої літери кожного слова.
  • Використовуйте верблюжий гільз. Починайте назви змінних з префікса малими літерами, а потім пишіть першу літеру кожного слова в назві з великої літери.

Ці приклади відповідають стандартам і умовностям:

  • Глобальна змінна:gblFocusedBorderColor
  • Контекстна змінна:locSuccessMessage
  • Змінна області видимості:scpRadius

Ці приклади не відповідають стандартам і їх важче зрозуміти:

  • dSub
  • rstFlds
  • hideNxtBtn
  • ttlOppCt
  • cFV
  • cQId

Уникайте коротких і загадкових імен змінних, таких EIDяк . Використовуйте EmployeeId натомість.

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

Імена колекцій

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

Ці приклади відповідають правилам іменування колекції:

  • colMenuItems
  • colThriveApps

Ці приклади не відповідають правилам щодо назв колекцій:

  • orderscoll
  • tempCollection

Порада

Коли додаток має багато колекцій, введіть префікс у панелі формул, щоб побачити список доступних колекцій. Якщо дотримуватися цих рекомендацій щодо назв колекцій, ви легко зможете знайти їх у панелі формул під час розробки додатку. Такий підхід веде до швидшої розробки додатків.

Коментарі та документація

Коли ви пишете код для своєї програми, зосередьтеся на додаванні чітких коментарів. Коментарі допомагають зрозуміти код пізніше і полегшують наступному розробнику роботу над project.

Power Apps підтримує два стилі коментарів для чіткішого коду: лінійні коментарі, які використовують подвійні косі косі (//) для однорядкових нотаток, та блочні коментарі, які використовують /* та */ для багаторядкових нотаток.

Коментарі до рядків

Додайте подвійну косу косу (//) до будь-якого рядка коду в Power Apps, щоб решта рядка була коментарем.

Використовуйте коментарі до рядків, щоб пояснити, що робить наступний рядок коду. Ви також можете використовувати їх, щоб тимчасово відключити рядок коду для тестування.

Ось приклад рядкового коментаря.

// ClearCollect function populates the Expenses2 collection with sample data
ClearCollect(
    Expenses2,
    // Entry 1: Client hosted meet and greet
    {
        Title: "Client hosted meet and greet:",
        ID: "4"
        // additional properties  
    }
)

Як заблокувати коментарі

Текст між /* і */ є блоковим коментарем. Заблоковані коментарі можуть займати кілька рядків, на відміну від рядкових коментарів, які охоплюють лише один рядок.

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

Для кращої організації коду додавайте коментарі після використання функції «Формат тексту». Цей підхід допомагає, коли ваші коментарі з'являються перед кодовим блоком.

/*
    Patch Operation to Insert Data:
    - Inserts a new employee record into the 'Employee' entity.
    - Adds corresponding department details to the 'Department' entity.
    Note: Ensure that foreign key relationships and dependencies are maintained for data integrity.
*/
Patch(
    Employee,
    Defaults(Employee),
    {
        FirstName: "John",
        LastName: "Doe",
        Position: "Software Developer"
    }
)

Функція «Форматування тексту» відповідає таким правилам для коментарів:

  1. Якщо властивість починається з коментаря до блоку, до неї додається наступний рядок коду.
  2. Якщо властивість починається з коментаря до рядка, наступний рядок коду до неї не додається. В іншому випадку код закоментовується.
  3. Коментарі до рядків і блоків в інших місцях властивості додаються до попереднього рядка коду.

Не турбуйтеся про те, що ви додасте занадто багато або занадто довгі коментарі. Power Apps видаляє всі коментарі при створенні пакету клієнтського додатку. Коментарі не впливають на розмір пакета, швидкість завантаження додатку чи час завантаження.

Сучасний дизайнер додатків з коментарями

У Power Apps використовуйте функції коментування як у Power Apps Studio, так і в сучасному дизайнері додатків.

Щоб додати коментарі в Power Apps Studio, скористайтеся такими методами:

  • Клацніть правою кнопкою миші на трьох крапках («...») будь-якого елемента в режимі перегляду дерева.
  • Клацніть правою кнопкою миші компонент в області полотна.
  • Виберіть кнопку «Коментарі », розташовану на панелі команд у верхньому правому куті екрана.

Коли ви згадуєте колегу в коментарі, використовуйте символ «@», а потім його ім’я. Ця дія надсилає повідомлення на електронний лист особі, яку ви позначаєте. Якщо позначений користувач не має access до додатку, Power Apps пропонує поділитися додатком з ним.

Скріншот додатку для витрат, де людина, згадана @ у коментарі.

Відступи і форматування

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

Відступу

Power Apps не вимагає суворого відступу. Використовуйте пробіли, щоб розділити різні частини формул. Натисніть пробіл кілька разів, щоб створити відступ.

Розриви рядків

Розбийте довгі формули на кілька рядків, щоб їх було легше читати. Натисніть клавішу Enter, щоб додати розрив рядка в рядку формул.

Використання команди «Формат тексту»

Команда Format text у панелі формул додає відступи, інтервали та розриви рядків до вашого Power Apps коду. Використовуйте команду Format text, щоб зберегти послідовний стиль кодування у вашому додатку Canvas і допомогти уникнути помилок.

скріншот Power Apps Studio з виділеною командою Format text.

Наступний крок

Оптимізація коду

  • Last updated on