Czytelność kodu

Konwencje nazewnictwa

Ogólne konwencje nazewnictwa

Ta sekcja opisuje konwencje nazewnictwa "camel case" i "Pascal case". Jeśli znasz już te terminy, możesz przejść dalej.

Przypadek wielbłąda

W kontrolkach i zmiennych należy używać camel case. Camel case zaczyna się od prefiksu z małymi literami, usuwa wszystkie spacje z nazw obiektów lub zmiennych i pisze wielką literą pierwszą literę każdego słowa po pierwszym. Na przykład, kontrolka wprowadzania tekstu może mieć nazwę txtUserEmailAddress.

Przypadek Pascal

W przypadku źródeł danych należy używać Pascal case. Pascal case czasami nazywa się nazywane "upper camel case". Podobnie jak ten zapis, Pascal case usuwa wszystkie spacje i zamienia pierwsze litery słów na wielkie. Jednak w przeciwieństwie do camel case, w Pascal case również pierwsze słowo jest pisane wielką literą. Na przykład popularnym źródłem danych w PowerApps jest łącznik Microsoft Office 365 Users, który w kodzie ma nazwę Office365Users.

Nazwy ekranów

Nazwy ekranów powinny odzwierciedlać ich przeznaczenie, aby ułatwić nawigację po złożonych aplikacjach w Power Apps Studio.

Mniej oczywiste jest to, że nazwy ekranów są odczytywane na głos przez czytniki ekranu, które są niezbędne dla użytkowników, którzy mają potrzeby w zakresie dostępności wzrokowej. Dlatego konieczne jest używanie prostego języka do nazywania ekranów, a nazwy muszą zawierać spacje i nie mogą zawierać skrótów. Zalecamy również zakończenie nazwy słowem "Ekran", aby kontekst był zrozumiały podczas ogłaszania nazwy.

Oto kilka dobrych przykładów:

• Home_Screen lub Home Screen
• Search_Screen lub Search Screen

Te przykładowe nazwy ekranowe są mniej zrozumiałe:

• Home
• LoaderScreen
• EmpProfDetails
• Thrive Help

Nazwy kontrolek

Wszystkie nazwy formantów na kanwie powinny używać camel case. Powinny one zaczynać się od trzyznakowego deskryptora typu, po którym następuje cel kontrolki. Takie podejście pomaga zidentyfikować typ kontroli i ułatwia tworzenie formuł i wyszukiwanie. Na przykład, lblUserName wskazuje, że kontrolka jest etykietą.

Poniższa tabela przedstawia skróty popularnych elementów sterujących.

Szczegółowa lista kontrolek i ich właściwości została opisana w Kontrolki referencyjne.

Oto kilka złych przykładów:

• zipcode
• Next

Kiedy konsekwentnie nazywasz swoje kontrolki, Twoja aplikacja jest bardziej przejrzysta w widoku nawigacji, a Twój kod jest również bardziej przejrzysty.

Nazwy źródeł danych

Po dodaniu źródła danych do aplikacji nie można zmienić jego nazwy w aplikacji Power Apps. Nazwa jest dziedziczona z łącznika źródłowego lub encji danych, które pochodzą z łącznika.

Oto kilka przykładów:

• Nazwa odziedziczona z łącznika źródłowego: Łącznik Office 365 Users ma w kodzie nazwęOffice365Users.
• Encje danych pochodzące z połączenia: Lista Microsoft SharePoint o nazwie Employees jest zwracana z łącznika SharePoint. Dlatego nazwa źródła danych w kodzie to Employees. Ta sama aplikacja Power Apps może również korzystać z tego samego łącznika SharePoint w celu uzyskania dostępu do listy SharePoint o nazwie Contractors. W tym przypadku nazwa źródła danych w kodzie to Contractors.

Więcej informacji na temat łączników i połączeń można znaleźć w Przegląd łączników aplikacji opartej na kanwie dla Power Apps.

Łączniki o standardowym działaniu

W standardowych łącznikach akcji, które eksponują funkcje, takie jak LinkedIn, nazwa źródła danych i jego operacje używają Pascal case. Na przykład źródło danych LinkedIn ma nazwę LinkedIn i operację o nazwie ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Łączniki niestandardowe

Niestandardowe łączniki używane do łączenia się z niestandardowymi interfejsami programowania aplikacji (API), takimi jak usługi lub interfejsy API linii biznesowej utworzone przez firmę. Mogą być tworzone przez dowolnego twórcę w środowisku. Zalecamy stosowanie Pascal case dla nazwy źródła danych i jego operacji. Należy tylko pamiętać, że nazwa łącznika niestandardowego i sposób jego wyświetlania w PowerApps mogą się różnić.

Rozważmy ten przykład niestandardowego łącznika o nazwie MS Auction Item Bid API.

Jednak po utworzeniu połączenia z tego łącznika i dodaniu go do aplikacji PowerApps jako źródła danych, pojawia się ono jako AuctionItemBidAPI.

Aby odkryć przyczynę, można poszukać w pliku OpenAPI atrybutu title, który zawiera tekst Auction Item Bid API.

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

Power Apps usuwa wszystkie spacje z tej wartości atrybutu i używa jej jako nazwy źródła danych.

Tabele danych Excel

PowerApps używa DataTables w Microsoft Microsoft Excel do łączenia się z danymi w arkuszach Excel. Należy pamiętać o tych kwestiach podczas tworzenia dokumentów Excel jako źródeł danych:

• Nadaj swoim tabelom danych opisowe nazwy. Nazwa znajduje się w aplikacji Power Apps podczas pisania kodu, aby się z nią połączyć.
• Użyj jednej tabeli danych na arkusz.
• Nadaj taką samą nazwę DataTable i arkuszowi.
• Używaj opisowych nazw kolumn w DataTables.
• Użyj Pascal case. Każde słowo w nazwie DataTable powinno zaczynać się wielką literą, np. EmployeeLeaveRequests.

Nazwy zmiennych

Konwencje nazewnictwa zmiennych w aplikacjach opartych na kanwie są ważne dla zachowania czytelności, spójności i przejrzystości projektów Power Apps. Chociaż nie jest egzekwowany żaden ścisły standard, przyjęcie spójnej konwencji nazewnictwa w całej aplikacji kanwy może ułatwić Tobie i innym współpracownikom zrozumienie, używanie i zarządzanie zmiennymi.

• Używaj camel case, w którym pierwsza litera każdego słowa jest wielka, z wyjątkiem pierwszego słowa.
• Wybierz znaczące i opisowe nazwy, które jasno opisują cel lub treść zmiennej. Unikaj zbyt ogólnych nazw, takich jak temp lub var1. Zamiast tego używaj nazw opisowych, takich jak userEmail lub totalAmount.
• Rozważ użycie przedrostków lub przyrostków do wskazania typu zmiennej. Na przykład:
  • strUserName dla zmiennej tekstowej/stringa
  • numTotalAmount dla zmiennej numerycznej
  • boolIsEnabled dla zmiennej logicznej
  • locVarName dla zmiennych lokalnych/zmiennych kontekstowych
  • gblVarLoginUser dla zmiennych globalnych
• Zdecyduj, czy zmienne powinny być nazywane w liczbie pojedynczej czy mnogiej i trzymaj się tej konwencji. Na przykład, konsekwentnie używaj userCount lub users.
• Unikaj używania zastrzeżonych słów lub nazw, które mogą kolidować z funkcjami lub słowami kluczowymi Power Apps. Listę zastrzeżonych słów można znaleźć w dokumentacji Power Apps.
• Rozważ użycie prefiksów, które zapewniają kontekst użycia lub zakresu zmiennej. Na przykład:
  • frm dla zmiennych formularza
  • col dla kolekcji
  • var dla zmiennych ogólnego przeznaczenia
• Unikaj znaków specjalnych. Zachowaj nazwy alfanumeryczne i unikaj znaków specjalnych lub spacji. Trzymaj się liter i cyfr.

Power Apps pozwala zmiennym kontekstowym i globalnym mieć te same nazwy. Może to powodować zamieszanie, ponieważ formuły domyślnie używają zmiennych kontekstowych, chyba że zostanie użyty operator ujednoznaczniania.

Unikaj takich sytuacji, stosując się do poniższych konwencji:

• Przedrostek zmiennych kontekstowych z loc.
• Przedrostek zmiennych globalnych to gbl.
• Nazwa po prefiksie powinna wskazywać intencję/przeznaczenie zmiennej. Można użyć wielu słów i nie trzeba ich oddzielać żadnymi znakami specjalnymi, takimi jak spacje lub podkreślenia, jeśli pierwsza litera każdego słowa jest wielka.
• Use camel case. Nazwy zmiennych należy rozpoczynać przedrostkiem pisanym małymi literami, a następnie wielką literą każdego słowa w nazwie.

Przykłady te są zgodne ze standardami i konwencjami:

• Zmienna globalna: gblFocusedBorderColor

• Zmienna kontekstowa:locSuccessMessage

• Zmienna zakresu:scpRadius

Te przykłady nie są zgodne ze standardami i są trudniejsze do zrozumienia:

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

Unikaj krótkich i kryptycznych nazw zmiennych, takich jak EID. Zamiast Use EmployeeId.

Gdy w aplikacji jest wiele zmiennych, wystarczy wpisać prefiks na pasku formuły, aby wyświetlić listę dostępnych zmiennych. Jeśli zastosujesz się do tych wskazówek, aby nazwać swoje zmienne, będziesz mógł je łatwo znaleźć na pasku formuły podczas tworzenia aplikacji. Ostatecznie takie podejście prowadzi do szybszego rozwoju aplikacji.

Nazwy kolekcji

• Należy opisać treść kolekcji. Zastanów się, co zawiera kolekcja i/lub jak jest używana, a następnie nadaj jej odpowiednią nazwę.
• Kolekcje powinny być poprzedzone przedrostkiem col.
• Nazwa po prefiksie powinna wskazywać zamiar lub cel kolekcji. Można użyć wielu słów i nie trzeba ich oddzielać spacjami ani podkreśleniami, jeśli pierwsza litera każdego słowa jest wielka.
• Use camel case. Nazwy kolekcji należy rozpoczynać przedrostkiem col pisanym małą literą, a następnie wielką literą każdego słowa w nazwie.

Przykłady te są zgodne z konwencją nazw kolekcji:

• colMenuItems
• colThriveApps

Przykłady te nie są zgodne z konwencją nazw kolekcji:

• orderscoll
• tempCollection

Uwagi i dokumentacja

Pisząc kod dla aplikacji, skup się na dodawaniu jasnych komentarzy. Komentarze pomagają później zrozumieć kod i ułatwiają pracę nad projektem kolejnemu programiście.

Aplikacja Power Apps obsługuje dwa style komentarzy, które ułatwiają zrozumienie kodu: komentarze wierszowe, w których do notatek jednowierszowych używane są podwójne ukośniki (//), oraz komentarze blokowe, w których do notatek wielowierszowych używane są znaki /* i */.

Uwagi dotyczące wiersza

Dodaj podwójny ukośnik (//) do dowolnego wiersza kodu w Power Apps, aby reszta wiersza była komentarzem.

Użyj komentarzy wierszowych, aby wyjaśnić, co robi następny wiersz kodu. Możesz ich również użyć do tymczasowego wyłączenia wiersza kodu do testowania.

Oto przykład komentarza wierszowego.

// 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  
    }
)

Komentarze do bloku

Tekst pomiędzy /* i */ jest komentarzem blokowym. Komentarze blokowe mogą obejmować kilka wierszy, w przeciwieństwie do komentarzy liniowych, które obejmują tylko jeden wiersz.

Użyj komentarzy blokowych, aby uzyskać dłuższe wyjaśnienia, takie jak dokumentowanie nagłówka modułu kodu. Można ich również użyć do tymczasowego wyłączenia kilku wierszy kodu podczas testowania lub debugowania.

Aby uzyskać lepszą organizację kodu, dodaj komentarze po użyciu funkcji Formatuj tekst. Jest to pomocne, jeśli komentarze znajdują się przed blokiem kodu.

/*
    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"
    }
)

Funkcja Formatowanie tekstu jest zgodna z następującymi regułami dotyczącymi komentarzy:

1. Jeśli właściwość zaczyna się od komentarza blokowego, dodawany jest do niej następny wiersz kodu.
2. Jeśli właściwość zaczyna się od komentarza wiersza, następny wiersz kodu nie jest do niej dodawany. W przeciwnym razie kod jest komentowany.
3. Komentarze wierszy i bloków w innych miejscach właściwości są dodawane do poprzedniego wiersza kodu.

Nie martw się, że dodasz zbyt wiele lub zbyt długie komentarze. Power Apps usuwa wszystkie komentarze podczas tworzenia pakietu aplikacji klienckiej, więc komentarze nie wpływają na rozmiar pakietu ani nie spowalniają pobierania aplikacji ani czasu ładowania.

Nowoczesny kreator aplikacji z komentarzami

W Power Apps najlepiej jest używać funkcji komentowania zarówno w Power Apps Studio, jak i w nowoczesnym projektancie aplikacji.

Aby dodać komentarze w Power Apps Studio, użyj następujących metod:

1. Kliknij prawym przyciskiem myszy wielokropek ("...") dowolnego produktu w widoku drzewa.
2. Kliknij prawym przyciskiem myszy składnik w obszarze kanwy.
3. Wybierz przycisk "Komentarze" znajdujący się na pasku poleceń w prawym górnym rogu ekranu.

Gdy wspomnisz o współpracowniku w komentarzu, użyj symbolu "@", a następnie jego imienia i nazwiska. Spowoduje to wysłanie wiadomości e-mail z powiadomieniem do osoby, którą oznaczysz. Jeśli oznaczony użytkownik nie ma dostępu do aplikacji, Power Apps wyświetla monit o udostępnienie mu aplikacji.

Wcięcia i formatowanie

Wcięcia i formatowanie w Power Apps pomagają zachować przejrzystość i porządek w aplikacji. Postępowanie zgodnie z najlepszymi rozwiązaniami sprawia, że formuły i kontrolki są bardziej czytelne.

Pasek formuły

Wcięcie

Power Apps nie wymusza ścisłego wcięcia, ale można używać spacji do oddzielania różnych obszarów formuł. Naciśnij spację kilka razy, aby utworzyć wcięcie.

Podziały wierszy

Podziel długie formuły na wiele wierszy, aby były łatwiejsze do odczytania. Naciśnij Enter, aby dodać podział wiersza na pasku formuły.

Użyj polecenia Formatuj tekst

Polecenie "Formatuj tekst" na pasku formuły dodaje do kodu Power Apps wcięcia, odstępy i podziały wierszy. Użyj polecenia "Formatuj tekst", aby zachować spójny styl kodowania w swojej aplikacji kanwy i zapobiec błędom.

Następny krok