Legibilitat del codi

La llegibilitat del codi és un aspecte important del desenvolupament d'aplicacions que sovint es passa per alt. El codi llegible és més fàcil d'entendre, mantenir i depurar.

Convencions de nomenclatura

Les convencions de nomenclatura coherents milloren significativament la llegibilitat del teu codi. T'ajuda a identificar ràpidament la finalitat de cada element de la teva aplicació i facilita la navegació pel teu codi.

Convencions generals de nomenclatura

Aquesta secció descriu les convencions de nomenclatura "camel case" i "Pascal case". Si ja esteu familiaritzat amb aquests termes, podeu avançar.

Estoig de camell

Fes servir el camerí Camel per als controls i variables. Les majúscules i minúscules comencen amb un prefix en minúscules, eliminen tots els espais dels noms d'objectes o variables i posen en majúscula la primera lletra de cada paraula després de la primera. Per exemple, un control d'entrada de text pot anomenar-se txtUserEmailAddress.

Cas Pascal

Utilitza el cas Pascal per a les fonts de dades. El cas Pascal de vegades es coneix com a "cas del camell superior". Com la caixa del camell, elimina tots els espais i posa en majúscula la primera lletra de les paraules. No obstant això, a diferència de camel case, Pascal case també escriu en majúscula la primera paraula. Per exemple, una font de dades comuna a Power Apps és el connector Microsoft Office 365 Users, que en el codi s'anomena Office365Users.

Noms de pantalla

Tria noms d'usuari que mostrin clarament la funció de la pantalla, cosa que facilita la navegació per aplicacions complexes a Power Apps Studio.

Els lectors de pantalla llegeixen els noms d'usuari en veu alta. Els usuaris amb necessitats d'accessibilitat visual depenen d'aquests lectors de pantalla. Utilitza un llenguatge senzill per als noms d'usuari, inclou espais i evita les abreviatures. Acaba cada nom amb la paraula "Screen" per donar un context clar quan s'anuncia el nom.

Aquí teniu alguns bons exemples:

  • Home_Screen o Home Screen
  • Search_Screen o Search Screen

Captura de pantalla que mostra una llista de noms d'usuari que segueixen el patró descrit.

Aquests noms de pantalla d'exemple són menys comprensibles:

  • Home
  • LoaderScreen
  • EmpProfDetails
  • Thrive Help

Noms de controls

Fes servir camelbox per a tots els noms de control del llenç. Comença amb un descriptor de tres caràcters, seguit de la finalitat del control. Aquest enfocament ajuda a identificar el tipus de control i facilita la creació de fórmules i la cerca. Per exemple, lblUserName indica que el control és una etiqueta.

La taula següent mostra les abreviatures dels controls comuns.

Nom del control Abreviatura
Distintiu BDG
Botó btn
Control de la càmera lleva
Llenç llauna
Targeta crd
Gràfics Chr
Casella de selecció chk
Col·lecció col
Quadre combinat CMB
Component CMP
Contenidor contra
Dates dte
Llista desplegable DRP
Formulari frm
Galeria gal
Agrupa PRFV
Capçalera Hdr
Text HTML htm
Icona ico
Imatge img
Botó d'informació info
Etiqueta Lbl
Enllaç lnk
Quadre de llista Lst
Micròfon micròfon
Microsoft Stream Str
Forma de la secció de la pàgina s
Entrada de llapis bolígraf
Power BI Tile PBI
Barra de progrés pbar
Valoració rtg
Editor de text enriquit Rte
Formes (rectangle, cercle, etc.) Shp
Control lliscant Sld
Llista de fitxes pestanya
Table TBL
Entrada de text txt
Temporitzador Tmr
Commutador TGL
Vídeo Vídeo

La llista detallada dels controls i les seves propietats es descriu a Referència de controls.

Nota

Els noms de control han de ser únics en una aplicació. Si un control es reutilitza en diverses pantalles, el nom de pantalla curt hauria de tenir un sufix. Per exemple, galBottomNavMenuHS on "HS" significa "Pantalla d'inici". Aquest enfocament facilita la referència al control en fórmules entre pantalles.

Aquí hi ha alguns mals exemples:

  • zipcode
  • Next

Quan anomeneu els controls de manera coherent, l'aplicació és més neta a la visualització de navegació i el codi també és més net.

Captura de pantalla de la vista de navegació que mostra els noms dels controls seguint el patró descrit.

Noms de fonts de dades

Quan afegeixes una font de dades a la teva aplicació, no pots canviar el nom a l'aplicació Power Apps. El nom s'hereta del connector d'origen o de les entitats de dades derivades de la connexió.

A continuació trobareu alguns exemples:

  • Name heretat del connector d'origen: El connector Office 365 Users s'anomena Office365Users al teu codi.
  • Entitats de dades derivades de la connexió: Una llista de Microsoft SharePoint anomenada Employees es retorna des del connector SharePoint. Per tant, el nom de la font de dades al teu codi és Employees. La mateixa aplicació Power Apps també pot utilitzar el mateix connector de SharePoint per access una llista de SharePoint anomenada Contractors. En aquest cas, el nom de la font de dades del codi és Contractors.

Aprèn més sobre connectors i connexions a la Visió general de connectors per a aplicacions de canvas.

Connectors d'acció estàndard

En connectors d'acció estàndard que exposen funcions, com LinkedIn, el nom de la font de dades i les seves operacions utilitzen majúscules Pascal. Per exemple, la font de dades LinkedIn s'anomena LinkedIn i té una operació anomenada ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Connectors personalitzats

Utilitza connectors personalitzats per connectar-te a interfícies de programació d'aplicacions (APIs) personalitzades, com ara serveis o APIs de línia de negoci que creï la teva empresa. Qualsevol creador del teu entorn pot crear connectors personalitzats. Utilitza la majúscula Pascal per al nom de la font de dades i les seves operacions. El nom del connector personalitzat i la manera com apareix a Power Apps poden variar.

Considereu aquest exemple d'un connector personalitzat anomenat MS Auction Item Bid API.

Captura de pantalla d'un connector anomenat MS Auction Item Bid API.

Quan crees una connexió des d'aquest connector i l'afegeixes a la teva aplicació de Power Apps com a font de dades, apareix com a AuctionItemBidAPI.

Captura de pantalla d'un connector que mostra que el nom és AuctionItemBidAPI.

Per descobrir-ne la raó, busca dins del fitxer OpenAPI un atribut de títol que contingui el text Auction Item Bid API.

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

Power Apps elimina tots els espais d'aquest valor d'atribut i l'utilitza com a nom de la teva font de dades.

Propina

Canvia el valor d'aquest atribut per un nom amb majúscula Pascal, com ara AuctionItemBidAPI i utilitza'l com a nom de la teva connexió personalitzada. Així, no hi ha confusió. Canvieu aquest valor abans d'importar el OpenAPI fitxer per crear el connector personalitzat.

Nota

Si utilitzes l'opció Create from blank en lloc d'importar un fitxer OpenAPI existent, Power Apps et demana el nom del connector personalitzat. Aquest nom és tant el nom del connector personalitzat com el valor de l'atribut títol dins del fitxer OpenAPI. Utilitza un nom amb majúscula Pascal, AuctionItemBidAPI per tal de mantenir la coherència i la senzillesa.

Taules de dades de l'Excel

Power Apps utilitza taules de dades a Microsoft Excel per connectar-se a dades en fulls de càlcul d'Excel. Tingueu en compte aquests punts quan creeu documents de l'Excel com a fonts de dades:

  • Doneu noms descriptius a les vostres DataTables. El nom apareix a l'aplicació Power Apps quan escrius el codi per connectar-hi.
  • Utilitzeu una taula de dades per full de càlcul.
  • Doneu el mateix nom a la taula de dades i al full de càlcul.
  • Utilitzeu noms de columna descriptius a les taules de dades.
  • Utilitzeu Pascal case. Cada paraula del nom de DataTable ha de començar amb una lletra majúscula, com ara EmployeeLeaveRequests.

Noms de variables

Les convencions de nomenclatura de les variables a les aplicacions Canvas són importants per mantenir la llegibilitat, la coherència i la claredat en els teus projectes Power Apps. Tot i que no s'aplica cap estàndard estricte, l'adopció d'una convenció de nomenclatura coherent a tota l'aplicació de llenç pot facilitar a vosaltres i a altres col·laboradors la comprensió, l'ús i la gestió de les variables.

  • Utilitzeu majúscules i minúscules, on la primera lletra de cada paraula està en majúscula excepte la primera paraula.
  • Trieu noms significatius i descriptius que descriguin clarament el propòsit o el contingut de la variable. Evita noms massa genèrics com temp o var1. En canvi, utilitza noms descriptius com userEmail o totalAmount.
  • Considereu l'ús de prefixos o sufixos per indicar el tipus de variable. Per exemple:
    • strUserName per a una variable text/string
    • numTotalAmount per a una variable numèrica
    • boolIsEnabled per a una variable booleana
    • locVarName per a variables locals/variables de context
    • gblVarLoginUser per a variables globals
  • Decidiu si les vostres variables s'han d'anomenar en singular o plural i seguiu aquesta convenció. Per exemple, utilitzar userCount consistentment o users.
  • Evita utilitzar paraules o noms reservats que puguin entrar en conflicte amb funcions o paraules clau de Power Apps. Consulta la documentació de Power Apps per veure una llista de paraules reservades.
  • Penseu en utilitzar prefixos que proporcionin context sobre l'ús o l'abast de la variable. Per exemple:
    • frm per a variables de formulari
    • col per a col·leccions
    • var per a variables d'ús general
  • Eviteu els caràcters especials. Mantingueu els noms alfanumèrics i eviteu els caràcters especials o els espais. Cenyiu-vos a les lletres i els números.

Power Apps permet que les variables de context i globals comparteixin els mateixos noms. Aquesta compartició pot causar confusió perquè les teves fórmules utilitzen variables de context per defecte, tret que utilitzis l'operador de desambiguació.

Eviteu aquesta situació seguint aquestes convencions:

  • Prefixa les variables de context amb loc.
  • Prefixa les variables globals amb gbl.
  • El nom després del prefix hauria d'indicar la intenció o la finalitat de la variable. Pots utilitzar diverses paraules sense necessitat de separar-les per caràcters especials, com ara guions baixos, si capitalitzes la primera lletra de cada paraula.
  • Utilitza carcassa de camell. Comenceu els noms de les variables amb un prefix en minúscules i, a continuació, escriviu en majúscula la primera lletra de cada paraula del nom.

Aquests exemples segueixen estàndards i convencions:

  • Variable global:gblFocusedBorderColor
  • Variable de context:locSuccessMessage
  • Variable d'abast:scpRadius

Aquests exemples no segueixen els estàndards i són més difícils d'entendre:

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

Evita noms curts i críptics de variables com EID. Utilitzeu-lo EmployeeId en el seu lloc.

Quan una aplicació té moltes variables, escriu el prefix a la barra de fórmules per veure una llista de variables disponibles. Si segueixes aquestes pautes per anomenar les teves variables, les pots trobar fàcilment a la barra de fórmules mentre desenvolupes la teva aplicació. En última instància, aquest enfocament condueix a un desenvolupament d'aplicacions més ràpid i eficient.

Noms de col·leccions

  • Utilitza noms que descriguin el contingut de la col·lecció. Pensa què conté la col·lecció i com s'utilitza, i posa-li el nom en conseqüència.
  • Noms de col·lecció de prefixos amb col.
  • Utilitza el nom després del prefix per mostrar la intenció o la finalitat de la col·lecció. Pots utilitzar diverses paraules sense espais ni subratlles si poses la primera lletra en majúscula de cada paraula.
  • Utilitza carcassa de camell. Comença els noms de la col·lecció amb un prefix minúscul col i després posa en majúscula la primera lletra de cada paraula del nom.

Aquests exemples segueixen les convencions de noms de col·lecció:

  • colMenuItems
  • colThriveApps

Aquests exemples no segueixen les convencions de nom de col·lecció:

  • orderscoll
  • tempCollection

Propina

Quan una aplicació té moltes col·leccions, escriu el prefix a la barra de fórmules per veure una llista de col·leccions disponibles. Si segueixes aquestes pautes per anomenar les teves col·leccions, les pots trobar fàcilment a la barra de fórmules mentre desenvolupes la teva aplicació. Aquest enfocament condueix a un desenvolupament d'aplicacions més ràpid.

Comentaris i documentació

Quan escriviu codi per a la vostra aplicació, centreu-vos a afegir comentaris clars. Els comentaris t'ajuden a entendre el codi més endavant i faciliten que el proper desenvolupador treballi en el project.

Power Apps admet dos estils de comentari per fer el teu codi més clar: els comentaris de línia, que utilitzen barres dobles endavant (//) per a notes d'una sola línia, i els comentaris en bloc, que utilitzen /* i */ per a notes de diverses línies.

Comentaris de línia

Afegeix una doble barra diagonal (//) a qualsevol línia de codi de Power Apps per fer que la resta de la línia sigui un comentari.

Utilitzeu comentaris de línia per explicar què fa la següent línia de codi. També podeu utilitzar-los per desactivar temporalment una línia de codi per provar-la.

Aquí teniu un exemple d'un comentari de línia.

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

Bloquejar comentaris

El text entre /* i */ és un comentari en bloc. Els comentaris en bloc poden cobrir diverses línies, a diferència dels comentaris de línia, que només cobreixen una línia.

Utilitzeu comentaris de bloc per a explicacions més llargues, com ara documentar una capçalera de mòdul de codi. També podeu utilitzar-los per desactivar temporalment diverses línies de codi durant les proves o la depuració.

Per a una millor organització del codi, afegiu comentaris després d'utilitzar la funció Format de text. Aquest enfocament ajuda quan els teus comentaris apareixen abans d'un bloc de codi.

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

La funció Format text segueix aquestes regles per als comentaris:

  1. Si una propietat comença amb un comentari de bloc, s'hi afegeix la següent línia de codi.
  2. Si una propietat comença amb un comentari de línia, no s'hi afegeix la línia de codi següent. En cas contrari, el codi es comenta.
  3. Els comentaris de línia i bloc en altres llocs de la propietat s'afegeixen a la línia de codi anterior.

No us preocupeu per afegir massa comentaris o massa llargs. Power Apps elimina tots els comentaris quan crea el paquet d'aplicació client. Els comentaris no afecten la mida del paquet, la velocitat de descàrrega de l'aplicació ni els temps de càrrega.

Dissenyador d'aplicacions modern amb comentaris

A Power Apps, utilitza les funcions de comentaris tant de Power Apps Studio com del dissenyador d'aplicacions modern.

Per afegir comentaris a Power Apps Studio, utilitzeu aquests mètodes:

  • Feu clic amb el botó dret a les punts suspensius ("...") de qualsevol element de la vista d'arbre.
  • Feu clic amb el botó dret en un component de l'àrea del llenç.
  • Selecciona el botó de Comentaris situat a la barra de comandaments a la cantonada superior dreta de la pantalla.

Quan mencioneu un company en un comentari, utilitzeu el símbol "@" seguit del seu nom. Aquesta acció envia un correu electrònic de notificació a la persona que etiquetes. Si l'usuari etiquetat no té accés a l'aplicació, Power Apps et demana que comparteixis l'aplicació amb ell.

Captura de pantalla d'una aplicació de despeses que mostra una persona esmentada amb @ en un comentari.

Sagnat i format

La sagnada i el format ajuden a mantenir la teva aplicació clara i organitzada. Quan el teu codi està ben formatat, és més fàcil de llegir i entendre.

Sagnia

Power Apps no imposa una indentació estricta. Utilitza espais per separar diferents seccions de les teves fórmules. Prem la barra espaiadora diverses vegades per crear una indentació.

Salts de línia

Dividiu les fórmules llargues en diverses línies per fer-les més fàcils de llegir. Premeu Retorn per afegir un salt de línia a la barra de fórmules.

Utilitzar l'ordre Format de text

La comanda Format text a la barra de fórmula afegeix sagnat, espaiat i salts de línia al teu codi Power Apps. Utilitza la comanda Formatar text per mantenir un estil de codificació consistent a la teva aplicació canvas i per ajudar a evitar errors.

Captura de pantalla de Power Apps Studio amb la comanda Format text ressaltada.

Pas següent

Optimització de codi

  • Last updated on