Czytelność kodu

Czytelność kodu jest ważnym aspektem tworzenia aplikacji, który jest często pomijany. Czytelny kod jest łatwiejszy do zrozumienia, obsługi i debugowania.

Konwencje nazewnictwa

Spójne konwencje nazewnictwa znacznie zwiększają czytelność kodu. Ułatwia szybkie identyfikowanie przeznaczenia każdego elementu w aplikacji i ułatwia przechodzenie przez bazę kodu.

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

Użyj notacji camelCase dla kontrolek i zmiennych. 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

Użyj notacji Pascal dla źródeł danych. Pascal case czasami nazywa się "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 typowym źródłem danych w usłudze Power Apps jest łącznik Microsoft Office 365 Users o nazwie Office365Users w kodzie.

Nazwy ekranów

Wybierz nazwy ekranów, które wyraźnie pokazują przeznaczenie ekranu, co ułatwia przechodzenie przez złożone aplikacje w programie Power Apps Studio.

Czytniki ekranu czytają na głos nazwy ekranowe. Użytkownicy z potrzebami ułatwień dostępu do obrazów korzystają z tych czytników zawartości ekranu. Używaj prostego języka dla nazw użytkownika, uwzględniaj spacje i unikaj skrótów. Zakończ każdą nazwę wyrazem "Screen", aby podać jasny kontekst po ogłoszeniu 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

Użyj notacji camelCase dla wszystkich nazw kontrolek w kanwie. Zacznij od deskryptora typu trzyznakowego, a następnie celu 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
Odznaka	bdg
Przycisk	btn
Sterowanie kamerą	cam
Kanwa	może
Karta	crd
Wykresy	chr
CheckBox	chk
Kolekcja	col
Pole kombi	cmb
Składnik	cmp
Kontener	con
Daty	dte
Lista rozwijana	drp
Formularz	frm
Galeria	gal
Grupa	grp
Nagłówek	hdr
Tekst HTML	htm
Ikona	ico
obraz	img
Przycisk informacyjny	Informacje
Etykieta	lbl
Link	lnk
List box	lst
Mikrofon	mikrofon
Microsoft Stream	str
Kształt sekcji strony	sec
Wprowadzanie za pomocą pióra	długopis
Kafelek Power BI	pbi
Pasek postępu	pbar
Ocena	rtg
Edytor tekstu bogatego	rte
Kształty (prostokąt, okrąg i tak dalej)	shp
Suwak	sld
Lista kart	karta
Tabela	tbl
Wprowadzenie tekstu	Plik tekstowy (txt)
Czasomierz	tmr
Przełącznik	tgl
wideo	vid

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

Notatka

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ć 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 dziedziczona z łącznika źródłowego: łącznik Użytkownicy usługi Office 365 nosi nazwę Office365Users w kodzie.
• Jednostki danych pochodzące z połączenia: Lista Microsoft SharePoint o nazwie Employees jest zwracana z łącznika SharePoint. W związku z tym nazwa źródła danych w kodzie to Employees. Ta sama aplikacja usługi Power Apps może również używać tego samego łącznika programu SharePoint, aby uzyskać dostęp do listy programu SharePoint o nazwie Contractors. W tym przypadku nazwa źródła danych w kodzie to Contractors.

Dowiedz się więcej o łącznikach i połączeniach w Omówieniu łączników dla aplikacji kanwy.

Łą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ą notacji Pascala dla wielkich liter. Na przykład źródło danych LinkedIn nosi nazwę LinkedIn i ma operację o nazwie ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Łączniki niestandardowe

Łączniki niestandardowe umożliwiają łączenie się z niestandardowymi interfejsami programowania aplikacji (API), takimi jak usługi lub interfejsy API dla systemów biznesowych, które tworzy firma. Każdy twórca w danym środowisku może tworzyć łączniki niestandardowe. Użyj stylu języka Pascal dla nazwy źródła danych i operacji na nim. Nazwa łącznika niestandardowego i sposób jej wyświetlania w Power Apps mogą się różnić.

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

Po utworzeniu połączenia z tego łącznika i dodaniu go do aplikacji Power Apps jako źródła danych jest wyświetlany jako AuctionItemBidAPI.

Aby odnaleźć przyczynę, poszukaj w pliku OpenAPI atrybutu title zawierającego 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

Zmień wartość tego atrybutu na nazwę w formacie Pascal, taką jak AuctionItemBidAPI i użyj jej jako nazwy połączenia niestandardowego. W ten sposób nie ma zamieszania. Zmień tę wartość przed zaimportowaniem pliku OpenAPI w celu utworzenia niestandardowego łącznika.

Notatka

Jeśli używasz opcji Utwórz z pustego zamiast importowania istniejącego pliku OpenAPI, Power Apps wyświetli monit o nazwę łącznika niestandardowego. Ta nazwa jest zarówno nazwą łącznika niestandardowego, jak i wartością atrybutu title wewnątrz pliku OpenAPI. Użyj nazwy w formacie Pascal, takiej jak AuctionItemBidAPI , aby zachować spójność i prostotę.

Tabele danych Excel

Usługa Power Apps używa tabel DataTable w Microsoft Excel do nawiązywania połączenia z danymi w arkuszach programu 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 w celu nawiązania z nim połączenia.
• Użyj jednej tabeli danych na arkusz.
• Nadaj taką samą nazwę DataTable i arkuszowi.
• Używaj opisowych nazw kolumn w DataTables.
• Użyj stylu języka Pascal. Każde słowo w nazwie DataTable powinno zaczynać się wielką literą, np. EmployeeLeaveRequests.

Nazwy zmiennych

Konwencje nazewnictwa zmiennych w aplikacjach kanwy są ważne dla utrzymania czytelności, spójności i klarowności w projektach usługi 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 różnych wielkości liter, 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 nadmiernie ogólnych nazw, takich jak temp lub var1. Zamiast tego użyj 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/ciągu znaków
  • 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żywać userCount lub users.
• Unikaj używania zastrzeżonych słów lub nazw, które mogą powodować konflikt z funkcjami lub słowami kluczowymi Power Apps. Zapoznaj się z dokumentacją Power Apps, aby uzyskać listę zastrzeżonych słów.
• 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 umożliwia współużytkowanie zmiennych kontekstowych i zmiennych globalnych o tych samych nazwach. To udostępnianie może spowodować zamieszanie, ponieważ formuły domyślnie używają zmiennych kontekstowych, chyba że używasz operatora uściślania.

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

• Poprzedź zmienne kontekstowe przedrostkiem loc.
• Poprzedź zmienne globalne prefiksem gbl.
• Nazwa po prefiksie powinna wskazywać intencję lub przeznaczenie zmiennej. Można użyć wielu wyrazów bez konieczności oddzielania ich znakami specjalnymi, takimi jak podkreślniki, jeśli każdy wyraz rozpoczyna się wielką literą.
• Użyj notacji camelCase. Nazwy zmiennych należy rozpoczynać małymi literami, a następnie kapitalizować pierwszą 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 tajemniczych nazw zmiennych, takich jak EID. Użyj EmployeeId zamiast tego.

Gdy aplikacja ma wiele zmiennych, wpisz prefiks na pasku formuły, aby wyświetlić listę dostępnych zmiennych. Jeśli zastosujesz się do tych wytycznych, aby nazwać zmienne, możesz je łatwo znaleźć na pasku formuły podczas opracowywania aplikacji. Ostatecznie takie podejście prowadzi do szybszego i bardziej wydajnego tworzenia aplikacji.

Nazwy kolekcji

• Użyj nazw opisujących zawartość kolekcji. Zastanów się, co zawiera kolekcja i jak jest używana, i nazwij ją odpowiednio.
• Nazwy kolekcji poprzedzaj prefiksem col.
• Użyj nazwy po prefiksie, aby wyświetlić intencję lub cel kolekcji. Można użyć wielu wyrazów bez spacji lub podkreślników, jeśli zapiszesz każdą z pierwszych liter dużą literą.
• Użyj notacji camelCase. Rozpocznij nazwy kolekcji z prefiksem rozpoczynającym się od małej litery col, a następnie kapitalizuj pierwszą literę każdego wyrazu 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

Gdy aplikacja ma wiele kolekcji, wpisz prefiks na pasku formuły, aby wyświetlić listę dostępnych kolekcji. Jeśli zastosujesz się do tych wytycznych dotyczących nazewnictwa kolekcji, możesz je łatwo znaleźć na pasku formuły podczas opracowywania aplikacji. Takie podejście prowadzi do szybszego tworzenia aplikacji.

Uwagi i dokumentacja

Pisząc kod dla aplikacji, skup się na dodawaniu jasnych komentarzy. Komentarze pomagają zrozumieć kod później i ułatwić następnemu deweloperowi pracę nad project.

Power Apps obsługuje dwa style komentarzy, aby kod był czytelniejszy: komentarze liniowe, które używają podwójnych ukośników (//) dla jednoliniowych komentarzy, i komentarze blokowe, które używają /* i */ dla komentarzy wieloliniowych.

Komentarze liniowe

Dodaj podwójny ukośnik (//) do dowolnego wiersza kodu w Power Apps, aby utworzyć pozostałą część wiersza jako komentarz.

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 blokowe

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. Takie podejście pomaga, gdy komentarze pojawiają 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 w linii, 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ę o dodanie zbyt wielu lub zbyt długich komentarzy. Power Apps usuwa wszystkie komentarze podczas tworzenia pakietu aplikacji klienckiej. Komentarze nie mają wpływu na rozmiar pakietu, szybkość pobierania aplikacji ani czas ładowania.

Nowoczesny kreator aplikacji z komentarzami

W Power Apps użyj funkcji komentowania zarówno w programie Power Apps Studio, jak i w nowoczesnym projektancie aplikacji.

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

• Kliknij prawym przyciskiem myszy wielokropek ("...") dowolnego elementu w Widoku drzewa.
• Kliknij prawym przyciskiem myszy składnik w obszarze kanwy.
• 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. Ta akcja wysyła wiadomość e-mail z powiadomieniem do osoby, której tagujesz. Jeśli oznakowany użytkownik nie ma dostępu do aplikacji, usługa Power Apps wyświetli monit o udostępnienie aplikacji.

Wcięcia i formatowanie

Wcięcia i formatowanie pomagają zachować czytelność i organizowanie aplikacji. Gdy kod jest dobrze sformatowany, łatwiej jest je odczytać i zrozumieć.

Wcięcie

Power Apps nie wymusza ścisłych wcięć. Użyj spacji, aby oddzielić różne sekcje 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 Formatowanie tekstu na pasku formuły dodaje wcięcia, odstępy i podziały wierszy w kodzie Power Apps. Użyj polecenia Formatuj tekst , aby zachować spójny styl kodowania w aplikacji kanwy i pomóc w zapobieganiu błędom.

Informacje pokrewne

• Używaj spójnych konwencji nazewnictwa w przepływach w chmurze Power Automate
• Twórz czytelne i łatwe do utrzymania skrypty w przepływach na komputerze Power Automate

Następny krok

Optymalizacja kodu