Lizibilitatea codului

Lizibilitatea codului este un aspect important al dezvoltării aplicațiilor, adesea trecut cu vederea. Codul lizibil este mai ușor de înțeles, întreținut și depanat.

Convenții de denumire

Convențiile consistente de denumire îmbunătățesc semnificativ lizibilitatea codului tău. Te ajută să identifici rapid scopul fiecărui element din aplicație și facilitează navigarea prin baza de cod.

Convenții generale de denumire

Această secțiune descrie convențiile de denumire pentru „camel case” și „casel case”. Dacă sunteți deja familiarizați cu acești termeni, puteți trece peste.

Carcasă de cămilă

Folosește carcasa Camel pentru controale și variabile. Litera „camel” începe cu un prefix cu literă mică, elimină toate spațiile din numele obiectelor sau variabilelor și scrie cu majusculă prima literă a fiecărui cuvânt după prima. De exemplu, un control de introducere a textului ar putea fi denumit txtUserEmailAddress.

Cazul Pascal

Folosește cazul Pascal pentru sursele de date. Cazul Pascal este uneori denumit „cazul majusculă”. La fel ca în cazul camel, elimină toate spațiile și scrie cu majusculă prima literă a cuvintelor. Totuși, spre deosebire de cazul cămilei, cazul Pascal scrie și el cu majusculă primul cuvânt. De exemplu, o sursă comună de date în Power Apps este conectorul Microsoft Office 365 Users, care în cod se numește Office365Users.

Nume de ecran

Alege nume de utilizator care arată clar scopul ecranului, ceea ce face mai ușoară navigarea prin aplicații complexe în Power Apps Studio.

Cititorii de ecran citesc cu voce tare numele de utilizator. Utilizatorii cu nevoi de accesibilitate vizuală se bazează pe acești cititori de ecran. Folosește un limbaj simplu pentru numele de utilizator, include spații și evită abrevierile. Încheiați fiecare nume cu cuvântul "Screen" pentru a oferi un context clar când numele este anunțat.

Iată câteva exemple bune:

  • Home_Screen sau Home Screen
  • Search_Screen sau Search Screen

Captură de ecran care arată o listă de nume de utilizator care urmează modelul descris.

Aceste exemple de nume de utilizator sunt mai puțin ușor de înțeles:

  • Home
  • LoaderScreen
  • EmpProfDetails
  • Thrive Help

Numele de control

Folosește camel case pentru toate numele de control de pe pânză. Începe cu un descriptor de tip de trei caractere, urmat de scopul controlului. Această abordare ajută la identificarea tipului de control și facilitează construirea de formule și căutarea. De exemplu, lblUserName indică faptul că controlul este o etichetă.

Următorul tabel prezintă abrevierile pentru controalele comune.

Numele controlului Abreviere
Ecuson clădire
Buton btn
Controlul camerei cameră
Pânză poate
Card card
Diagrame cronologie
Casetă de selectare pui
Colecție col
Casetă combo cmb
Componentă cmp
Container con
Date dată
Listă verticală drp
Formular De la
Galerie fată
Grupare grup
Antet HDR
Text HTML htm
Pictogramă icoană
Imagine imagine
Buton Informații informații
Etichetă lbl
Link link
Casetă listă listă
Microfon microfon
Microsoft Stream str
Forma secțiunii de pagină secunde
Intrare cu stilou stilou
Power BI Tile PBI
Bară de progres Bară de presiune
Evaluare rtg
Editor de text îmbogățit rte
Forme (dreptunghi, cerc etc.) shp
Cursor sld
Listă de file tab
Tabel masă
Introducere text txt
Cronometru tmr
Comutator tgl
Video videoclip

Lista detaliată a controalelor și proprietățile acestora este descrisă în Referința controalelor.

Notă

Numele controalelor trebuie să fie unice în întreaga aplicație. Dacă un control este reutilizat pe mai multe ecrane, numele scurt al ecranului trebuie să aibă un sufix. De exemplu, galBottomNavMenuHS, unde „HS” înseamnă „Ecran principal”. Această abordare facilitează referirea la control în formule pe mai multe ecrane.

Iată câteva exemple proaste:

  • zipcode
  • Next

Când denumești controalele în mod constant, aplicația este mai curată în vizualizarea de navigare, iar codul este și el mai curat.

Captură de ecran a vizualizării de navigare care arată numele comenzilor după modelul descris.

Numele surselor de date

Când adaugi o sursă de date în aplicația ta, nu poți schimba numele în aplicația Power Apps. Numele este moștenit de la conectorul sursă sau de la entitățile de date derivate din conexiune.

Iată câteva exemple:

  • Nume moștenit de la conectorul sursă: Conectorul Office 365 Users se numește Office365Users în codul tău.
  • Entități de date derivate din conexiune: O listă Microsoft SharePoint numită Employees este returnată din conectorul SharePoint. Prin urmare, numele sursei de date din codul tău este Employees. Aceeași aplicație Power Apps poate folosi și același conector SharePoint pentru a access o listă SharePoint numită Contractors. În acest caz, numele sursei de date din cod este Contractors.

Află mai multe despre conectori și conexiuni în Prezentare generală a conectorilor pentru aplicațiile de tip canvas.

Conectori de acțiune standard

În conectorii standard de acțiune care expun funcții, cum ar fi LinkedIn, numele sursei de date și operațiunile sale folosesc carcasa Pascal. De exemplu, sursa de date LinkedIn se numește LinkedIn și are o operație numită ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Conectorii particularizați

Folosește conectori personalizați pentru a te conecta la interfețe de programare a aplicațiilor (API-uri) personalizate, cum ar fi serviciile sau API-urile de linie de afaceri create de compania ta. Orice creator din mediul tău poate crea conectori personalizați. Folosește carcasa Pascal pentru numele sursei de date și pentru operațiunile acesteia. Numele conectorului personalizat și modul în care apare în Power Apps pot difere.

Luați în considerare acest exemplu de conector personalizat numit MS Auction Item Bid API.

Captură de ecran a unui conector numit MS Auction Item Bid API.

Când creezi o conexiune de la acest conector și îl adaugi în aplicația ta de Power Apps ca sursă de date, apare ca AuctionItemBidAPI.

Captură de ecran cu un conector care arată că numele este AuctionItemBidAPI.

Pentru a descoperi motivul, căutați în fișierul OpenAPI un atribut titlu care conține textul Auction Item Bid API.

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

Power Apps elimină toate spațiile din această valoare a atributului și o folosește ca nume al sursei tale de date.

Sfat

Schimbă valoarea acestui atribut într-un nume cu majusculă Pascal, cum ar fi AuctionItemBidAPI și folosește-l ca nume al conexiunii tale personalizate. Astfel, nu există confuzii. Modificați această valoare înainte de a importa fișierul OpenAPI pentru a crea conectorul personalizat.

Notă

Dacă folosești opțiunea Create dintr-un blank în loc să importi un fișier OpenAPI existent, Power Apps îți cere numele de conector personalizat. Acest nume este atât numele conectorului personalizat, cât și valoarea atributului titlu din fișierul OpenAPI. Folosește un nume cu majusculă Pascal, AuctionItemBidAPI de exemplu pentru a menține lucrurile consistente și simple.

Tabele de date Excel

Power Apps folosește DataTables în Microsoft Excel pentru a se conecta la date din foi de calcul Excel. Rețineți aceste aspecte atunci când creați documente Excel ca surse de date:

  • Dați tabelelor DataTable nume descriptive. Numele apare în aplicația Power Apps când scrii codul pentru a te conecta la ea.
  • Folosește un DataTable per foaie de lucru.
  • Dați același nume tabelului DataTable și foii de calcul.
  • Folosiți nume descriptive ale coloanelor în DataTables.
  • Folosește carcasa Pascal. Fiecare cuvânt din numele DataTable trebuie să înceapă cu o literă majusculă, cum ar fi EmployeeLeaveRequests.

Nume de variabile

Convențiile de denumire pentru variabile în aplicațiile Canvas sunt importante pentru menținerea lizibilității, consistenței și clarității în proiectele tale Power Apps. Deși nu se impune niciun standard strict, adoptarea unei convenții de denumire consecvente în aplicația dvs. pe pânză poate facilita înțelegerea, utilizarea și gestionarea variabilelor de către dvs. și alți colaboratori.

  • Se folosește majuscula, unde prima literă a fiecărui cuvânt se scrie cu majusculă, cu excepția primului cuvânt.
  • Alegeți nume semnificative și descriptive care descriu clar scopul sau conținutul variabilei. Evită denumiri prea generice precum temp sau var1. În schimb, folosește denumiri descriptive precum userEmail sau totalAmount.
  • Luați în considerare utilizarea prefixelor sau sufixelor pentru a indica tipul de variabilă. De exemplu:
    • strUserName pentru o variabilă text/șir de caractere
    • numTotalAmount pentru o variabilă numerică
    • boolIsEnabled pentru o variabilă booleană
    • locVarName pentru variabile locale/variabile de context
    • gblVarLoginUser pentru variabile globale
  • Decideți dacă variabilele ar trebui denumite la singular sau la plural și respectați această convenție. De exemplu, folosește userCount constant sau users.
  • Evită să folosești cuvinte sau nume rezervate care ar putea intra în conflict cu funcțiile sau cuvintele-cheie Power Apps. Verifică documentația Power Apps pentru o listă de cuvinte rezervate.
  • Luați în considerare utilizarea prefixelor care oferă context despre utilizarea sau domeniul de aplicare al variabilei. De exemplu:
    • frm pentru variabile de formular
    • col pentru colecții
    • var pentru variabile de uz general
  • Evitați caracterele speciale. Păstrați numele alfanumerice și evitați caracterele speciale sau spațiile. Rămâi la litere și cifre.

Power Apps permite variabilelor de context și variabilelor globale să poarte aceleași denumiri. Această partajare poate cauza confuzie deoarece formulele tale folosesc implicit variabile de context, cu excepția cazului în care folosești operatorul de dezambiguizare.

Evitați această situație respectând aceste convenții:

  • Prefixați variabilele de context cu loc.
  • Prefixați variabilele globale cu gbl.
  • Numele după prefix ar trebui să indice intenția sau scopul variabilei. Poți folosi mai multe cuvinte fără a fi nevoie să le separi prin caractere speciale, cum ar fi subliniere, dacă scrii cu majusculă prima literă a fiecărui cuvânt.
  • Folosește carcasă pentru cămile. Începeți numele variabilelor cu un prefix cu litere mici, apoi scrieți cu majusculă prima literă a fiecărui cuvânt din nume.

Aceste exemple respectă standardele și convențiile:

  • Variabilă globală:gblFocusedBorderColor
  • Variabilă de context:locSuccessMessage
  • Variabilă de domeniu:scpRadius

Aceste exemple nu respectă standardele și sunt mai greu de înțeles:

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

Evitați denumirile scurte și criptice de variabile, cum ar fi EID. Folosește EmployeeId în schimb.

Când o aplicație are multe variabile, tastează prefixul în bara de formule pentru a vedea o listă de variabile disponibile. Dacă urmezi aceste recomandări pentru a-ți numi variabilele, le poți găsi ușor în bara de formule pe măsură ce îți dezvolți aplicația. În cele din urmă, această abordare conduce la o dezvoltare mai rapidă și mai eficientă a aplicațiilor.

Numele de colecție

  • Folosește denumiri care descriu conținutul colecției. Gândește-te ce conține colecția și cum este folosită, și denumește-o în consecință.
  • Denumirile colecțiilor prefixe cu col.
  • Folosește numele după prefix pentru a arăta intenția sau scopul colecției. Poți folosi mai multe cuvinte fără spații sau sublinii dacă scrii cu majusculă prima literă a fiecărui cuvânt.
  • Folosește carcasă pentru cămile. Începe numele colecțiilor cu un prefix mic col , apoi scrie cu majusculă prima literă a fiecărui cuvânt din nume.

Aceste exemple respectă convențiile de denumire a colecțiilor:

  • colMenuItems
  • colThriveApps

Aceste exemple nu respectă convențiile de denumire a colecțiilor:

  • orderscoll
  • tempCollection

Sfat

Când o aplicație are multe colecții, tastează prefixul în bara de formule pentru a vedea o listă cu colecțiile disponibile. Dacă urmezi aceste reguli pentru denumirea colecțiilor tale, le poți găsi ușor în bara de formule pe măsură ce îți dezvolți aplicația. Această abordare duce la o dezvoltare mai rapidă a aplicațiilor.

Comentarii și documentație

Când scrii cod pentru aplicația ta, concentrează-te pe adăugarea de comentarii clare. Comentariile te ajută să înțelegi codul mai târziu și fac mai ușor pentru următorul dezvoltator să lucreze la proiect.

Power Apps suportă două stiluri de comentarii pentru a face codul mai clar: comentariile de linie, care folosesc bârfe duble înainte (//) pentru notele cu o singură linie, și comentariile bloc, care folosesc /* și */ pentru notele cu mai multe linii.

Comentarii pe rând

Adaugă o dublă oblică înainte (//) la orice linie de cod din Power Apps pentru a face ca restul liniei să fie un comentariu.

Folosește comentarii pe linie pentru a explica ce face următoarea linie de cod. De asemenea, le puteți folosi pentru a dezactiva temporar o linie de cod pentru testare.

Iată un exemplu de comentariu pe o linie.

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

Blocați comentariile

Textul dintre /* și */ este un comentariu bloc. Comentariile bloc pot acoperi mai multe rânduri, spre deosebire de comentariile pe rând, care acoperă doar un rând.

Folosește comentarii în bloc pentru explicații mai lungi, cum ar fi documentarea unui antet de modul de cod. De asemenea, le puteți folosi pentru a dezactiva temporar mai multe linii de cod în timpul testării sau depanării.

Pentru o mai bună organizare a codului, adăugați comentarii după ce utilizați funcția Formatare text. Această abordare ajută atunci când comentariile tale apar înaintea unui bloc de cod.

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

Funcția Formatare text respectă aceste reguli pentru comentarii:

  1. Dacă o proprietate începe cu un comentariu de bloc, următoarea linie de cod este adăugată la aceasta.
  2. Dacă o proprietate începe cu un comentariu pe o linie, următoarea linie de cod nu este adăugată la aceasta. Altfel, codul este comentat.
  3. Comentariile la nivel de linie și bloc din altă parte a proprietății sunt adăugate la linia anterioară de cod.

Nu vă faceți griji dacă adăugați prea multe sau prea lungi comentarii. Power Apps elimină toate comentariile când creează pachetul aplicației client. Comentariile nu afectează dimensiunea pachetului, viteza de descărcare a aplicației sau timpii de încărcare.

Designer de aplicații moderne cu comentarii

În Power Apps, folosește funcțiile de comentarii atât în Power Apps Studio, cât și în designul modern de aplicații.

Pentru a adăuga comentarii în Power Apps Studio, folosește următoarele metode:

  • Faceți clic dreapta pe punctele de suspensie („...”) ale oricărui element din vizualizarea arborescentă.
  • Faceți clic dreapta pe o componentă din zona pânzei.
  • Selectează butonul Comentarii situat în bara de comenzi din colțul din dreapta sus al ecranului.

Când menționezi un coleg într-un comentariu, folosește simbolul „@” urmat de numele său. Această acțiune trimite un email de notificare persoanei pe care o etichetezi. Dacă utilizatorul etichetat nu are acces la aplicație, Power Apps te solicită să partajezi aplicația cu el.

Captură de ecran cu o aplicație de cheltuieli care arată o persoană menționată cu @ într-un comentariu.

Indentare și formatare

Indentarea și formatarea ajută la menținerea aplicației clare și organizate. Când codul tău este bine formatat, este mai ușor de citit și de înțeles.

Indentare

Power Apps nu impune indentări stricte. Folosește spații pentru a separa diferite secțiuni ale formulelor tale. Apasă bara de spațiu de mai multe ori pentru a crea o adâncitură.

Sfârșituri de linie

Împărțiți formulele lungi în mai multe rânduri pentru a le face mai ușor de citit. Apăsați Enter pentru a adăuga o sfârșit de linie în bara de formule.

Utilizați comanda Format text

Comanda Format text din bara de formule adaugă indentare, spațiere și întreruperi de linie în codul Power Apps tău. Folosește comanda Format text pentru a menține un stil de codare consecvent în aplicația ta Canvas și pentru a preveni erorile.

Captură de ecran cu Power Apps Studio cu comanda Format text evidențiată.

Pasul următor

Optimizarea codului

  • Last updated on