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.

Camel case

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.

Pascal case

W przypadku źródeł danych należy używać Pascal case. Wielkość liter Pascala jest czasami określana jako "górne camel case". Podobnie jak w przypadku camel 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 łatwe do zrozumienia:

• 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.

Nazwa formantu	Skrót
Wskaźnik	bdg
Button	btn
Sterowanie kamerą	cam
Kanwa	can
Card	crd
Wykresy	chr
CheckBox	chk
Kolekcja	col
Pole kombi	cmb
Składnik	cmp
Container	con
Daty	dte
Lista rozwijana	drp
Formularz	frm
Galeria	gal
Grupowy	grp
Nagłówek	hdr
Tekst html	htm
Icon	ico
Image	img
Przycisk informacyjny	Informacje usługi
Etykieta	lbl
Łącze	lnk
List box	lst
Mikrofon	mic
Microsoft Stream	str
Kształt sekcji strony	sek.
Wprowadzanie za pomocą pióra	pen
Kafelek usługi Power BI	pbi
Pasek postępu	pbar
Rating	rtg
Edytor tekstu sformatowanego	rte
Kształty (prostokąt, okrąg i tak dalej)	shp
Suwak	sld
Lista kart	tbl
Table	tbl
Wprowadzenie tekstu	txt
Czasomierz	tmr
Toggle	tgl
Video	vid

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

Uwaga

Nazwy kontrolek muszą być unikalne w całej aplikacji. Jeśli kontrolka jest ponownie używana na wielu ekranach, krótka nazwa ekranu powinna mieć przyrostek. Na przykład galBottomNavMenuHS, gdzie "HS" oznacza "Ekran główny". Takie podejście ułatwia odwoływanie się do kontrolki w formułach na różnych ekranach.

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.

Porada

Zalecamy zmianę wartości tego atrybutu na nazwę w Pascal code, taką jak AuctionItemBidAPI i użycie jej jako nazwy niestandardowego połączenia. W ten sposób nie będzie żadnych nieporozumień. Zmień tę wartość przed zaimportowaniem pliku OpenAPI w celu utworzenia niestandardowego łącznika.

Uwaga

Jeśli użyjesz opcji Twórz z pustego zamiast importować istniejący plik OpenAPI, PowerApps wyświetli monit o podanie niestandardowej nazwy łącznika. Nazwa ta będzie używana zarówno jako nazwa niestandardowego łącznika, jak i jako wartość atrybutu tytuł wewnątrz pliku OpenAPI. Upewnij się, że używasz nazwy w Pascal code takiej jak AuctionItemBidAPI, aby zachować spójność i prostotę.

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.

Nietypowe i dynamiczne obiekty

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 opartej na kanwie 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

Porada

Jeśli w aplikacji dostępnych jest wiele kolekcji, wystarczy wpisać prefiks na pasku formuły, aby wyświetlić listę dostępnych kolekcji. Jeśli chodzi o zmienne, jeśli będziesz postępować zgodnie z tymi wskazówkami, aby nazwać swoje kolekcje, będziesz w stanie bardzo łatwo je znaleźć na pasku formuły podczas tworzenia aplikacji. Ostatecznie takie podejście prowadzi do szybszego rozwoju aplikacji.

Uwagi i dokumentacja

Podczas pisania kodu aplikacji należy podkreślać znaczenie kompleksowego komentowania. Komentarze te nie tylko służą jako pomocny przewodnik podczas ponownego odwiedzenia aplikacji kilka miesięcy później, ale także stanowią gest wdzięczności dla kolejnego dewelopera, który współpracuje przy projekcie.

Istnieją dwa podstawowe typy komentarzy zwiększające przejrzystość kodu: Power Apps obsługuje dwa style komentarzy: komentarze liniowe, oznaczone podwójnymi ukośnikami (//) dla uwag jednowierszowych oraz komentarze blokowe zamknięte w /* i */ dla adnotacji wielowierszowych.

Uwagi dotyczące wiersza

Dodanie podwójnego ukośnika (//) do dowolnej linii kodu w PowerApps oznacza pozostałą część linii (w tym //) jako komentarz.

Używaj komentarzy do linii, aby wyjaśnić funkcjonalność kolejnego kodu. Mogą one również służyć do tymczasowego wyłączenia linii kodu, co czyni je korzystnymi do celów testowych.

Ten przykład pokazuje użycie komentarzy liniowych.

// 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 zawarty w /* i */ jest rozpoznawany jako komentarz blokowy. W przeciwieństwie do komentarzy liniowych, które odnoszą się do pojedynczej linii, komentarze blokowe mogą obejmować wiele linii.

Komentarze blokowe są przydatne w przypadku wielowierszowych objaśnień, takich jak dokumentowanie nagłówka modułu kodu. Ułatwiają one również tymczasowe wyłączenie wielu linii kodu podczas testowania lub debugowania.

Aby zapewnić optymalną organizację kodu, zaleca się dodawanie komentarzy po użyciu funkcji Formatuj tekst. Jest to korzystne, jeśli komentarze poprzedzają blok 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 Formatuj tekst przestrzega tych zasad dla istniejących komentarzy:

1. Jeśli właściwość zaczyna się od komentarza blokowego, zostanie do niej dołączona następna linia kodu.
2. Jeśli właściwość zaczyna się od komentarza w linii, następna linia kodu nie zostanie do niej dołączona. W przeciwnym razie kod jest komentowany.
3. Komentarze liniowe i blokowe w innych miejscach właściwości zostaną dołączone do poprzedniej linii kodu.

Nie przejmuj się dodawaniem zbyt wielu lub zbyt długich komentarzy. Wszystkie komentarze są usuwane, gdy PowerApps tworzy pakiet aplikacji klienckiej. W związku z tym nie wpływają one na rozmiar pakietu ani nie spowalniają czasu pobierania lub ładowania aplikacji.

Nowoczesny kreator aplikacji z komentarzami

W Power Apps najlepszą praktyką dla twórców jest efektywne wykorzystanie funkcji komentowania zarówno w Power Apps Studio, jak i Modern App Designer.

Aby uzyskać optymalne zaangażowanie w Power Apps Studio, twórcom zaleca się dodawanie komentarzy przy użyciu 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.

Wspominając współpracowników w komentarzach, zaleca się używanie symbolu "@", po którym następuje ich imię i nazwisko. Powoduje to wysłanie wiadomości e-mail z powiadomieniem do oznaczonego etykietą współpracownika, zapewniając szybki dostęp do komentarza. W przypadku, gdy użytkownik z etykietą nie ma dostępu do aplikacji, twórca zostanie poproszony o udostępnienie mu aplikacji.

Wcięcia i formatowanie

W Power Apps wcięcia i formatowanie mają kluczowe znaczenie dla utrzymania przejrzystej i zorganizowanej struktury aplikacji. Przestrzeganie najlepszych praktyk poprawia czytelność formuł i kontrolek.

Pasek formuły

Wcięcie

Chociaż Power Apps nie wymusza ścisłego wcięcia, możesz użyć spacji, aby wizualnie oddzielić różne sekcje formuł. Naciśnij spację kilka razy, aby utworzyć efekt wcięcia.

Podziały wierszy

Długie formuły można podzielić na wiele wierszy, aby zwiększyć ich czytelność. Naciśnij klawisz Enter, aby utworzyć podział wiersza na pasku formuły.

Użyj polecenia Formatuj tekst

Polecenie "Formatuj tekst" na pasku formuły służy do stosowania wcięć, odstępów i podziałów wierszy w kodzie Power Apps. Użyj polecenia "Formatuj tekst", aby ustanowić jednolity styl kodowania w całej aplikacji opartej na kanwie, zapewniając bardziej wydajny i odporny na błędy proces rozwoju.

Następny krok

Optymalizacja kodu