Condividi tramite

Leggibilità del codice

Convenzione di denominazione

Convenzioni di denominazione generali

Questa sezione descrive le convenzioni di denominazione "notazione a cammello" e "Pascal case". Se hai già familiarità con questi termini, puoi andare avanti.

Notazione a cammello

Dovresti usare la notazione a cammello per controlli e variabili. La notaizone a cammello inizia con un prefisso minuscolo, rimuove tutti gli spazi dai nomi di oggetti o variabili e rende maiuscola la prima lettera di ogni parola dopo la prima. Ad esempio, è possibile assegnare un nome a un controllo di input di testo txtUserEmailAddress.

Pascal case

Dovresti usare la notazione Pascal case per le origini dati. La notazione Pascal è talvolta chiamata "notazione camel" (letteralmente "notazione camel maiuscola"). Come la notazione camel, rimuove tutti gli spazi e rende maiuscola la prima lettera delle parole. Tuttavia, a differenza della notazione a cammello, la notazione Pascal cse mette in maiuscolo la prima parola. Ad esempio, un'origine dati comune in PowerApps è il connettore Utenti di Microsoft Office 365, denominato Office365Users nel codice.

Nomi schermata

I nomi delle schermate devono riflettere lo scopo dello schermo, in modo che sia più semplice navigare tra le app complesse in Power Apps Studio.

Ciò che è meno ovvio è che i nomi visualizzati vengono letti ad alta voce dalle utilità di lettura dello schermo, necessari per gli utenti con esigenze di accessibilità visiva. Perciò, è fondamentale utilizzare un linguaggio semplice per denominare le schermate e che i nomi includano spazi e nessuna abbreviazione. Inoltre, ti consigliamo di terminare il nome con la parola "Schermata", in modo che il contesto venga compreso quando viene annunciato il nome.

Di seguito sono riportati alcuni esempi:

  • Home_Screen o Home Screen
  • Search_Screen o Search Screen

Screenshot che mostra un elenco di nomi di schermate che seguono il modello descritto

Questi nomi utente di esempio sono meno comprensibili:

  • Home
  • LoaderScreen
  • EmpProfDetails
  • Thrive Help

Nomi dei controlli

Tutti i nomi dei controlli della canvas dovrebbero utilizzare la notazione a cammello. Dovrebbero iniziare con un descrittore del tipo a tre caratteri, seguito dallo scopo del controllo. Questo approccio aiuta a identificare il tipo di controllo e semplifica la creazione di formule e la ricerca. Ad esempio, lblUserName indica che il controllo è un'etichetta.

La tabella seguente mostra le abbreviazioni per i controlli comuni.

Nome controllo Abbreviazione
Badge bdg
Button btn
Controllo fotocamera cam
Canvas can
Carta crd
Grafici chr
CheckBox chk
Raccolta col
Combo box cmb
Componente cmp
Contenitore con
Date dte
Elenco a discesa drp
Modulo frm
Raccolta gal
Raggruppa grp
Intestazione hdr
Testo Html htm
Icon ico
Image img
Pulsante Info Informazioni su
Label lbl
Collega lnk
Casella di riepilogo lst
Microfono mic
Microsoft Stream str
Forma della sezione della pagina secondi
Input penna pen
Riquadro Power BI pbi
Barra di avanzamento pbar
Rating rtg
Editor di testo RTF rte
Forme (rettangolo, cerchio e così via) shp
Dispositivo di scorrimento sld
Elenco schede tbl
Table tbl
Input di testo txt
Timer tmr
Attivazione/disattivazione tgl
Video vid

L'elenco dettagliato dei controlli e delle relative proprietà è descritto in Riferimento ai controlli.

Nota

I nomi dei controlli devono essere univoci in un'applicazione. Se un controllo viene riutilizzato su più schermi, il nome breve dello schermo deve avere un suffisso. Ad esempio galBottomNavMenuHS, dove "HS" significa "Schermata iniziale". Questo approccio semplifica il riferimento al controllo nelle formule in più schermate.

Di seguito sono riportati alcuni esempi:

  • zipcode
  • Next

Quando dai nomi coerenti ai tuoi controlli, la tua app è più pulita nella visualizzazione di navigazione e anche il tuo codice è più pulito.

Screenshot della vista di navigazione che mostra i nomi dei controlli seguendo lo schema

Nomi dell'origine dati

Quando aggiungi un'origine dati alla tua applicazione, il nome non può essere modificato nell'app Power Apps. Il nome viene ereditato dal connettore di origine o dalle entità dati derivate dalla connessione.

Di seguito sono riportati alcuni esempi.

  • Nome ereditato dal connettore di origine: il connettore Utenti di Office 365 è denominato namedOffice365Users nel codice.
  • Entità di dati derivate dalla connessione: un elenco Microsoft SharePoint denominato Employees viene restituito dal connettore SharePoint. Pertanto, il nome dell'origine dati nel codice è Dipendenti. La stessa app Power Apps può anche utilizzare lo stesso connettore SharePoint per accedere a un elenco SharePoint denominato Contractors. In questo caso, il nome dell'origine dati nel codice è Contractors.

Per ulteriori informazioni su connettori e connessioni, vedi Panoramica dei connettori delle app canvas per Power Apps.

Connettori azioni standard

Nei connettori di azione standard che espongono funzioni, come LinkedIn, il nome dell'origine dati e le relative operazioni utilizzano la notazione Pascal case. Ad esempio, l'origine dati LinkedIn si chiama LinkedIn e ha un'operazione denominata ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Connettori personalizzati

Connettori personalizzati utilizzati per connettersi alle interfacce di programmazione delle applicazioni (API) personalizzate come servizi o API line-of-business create dalla tua azienda. Possono essere creati da qualsiasi creatore nel tuo ambiente. Consigliamo la notazione di Pascal case per il nome dell'origine dati e le sue operazioni. Tieni presente che il nome del connettore personalizzato e il modo in cui appare in PowerApps possono differire.

Considera questo esempio di connettore personalizzato denominato MS Auction Item Bid API.

Screenshot di un connettore denominato API MS Auction Item Bid

Ma quando crei una connessione da questo connettore e la aggiungi alla tua app PowerApps come origine dati, apparirà come AuctionItemBidAPI.

Screenshot di un connettore che mostra che il nome è AuctionItemBidAPI

Per scoprire il motivo, puoi cercare all'interno del file OpenAPI per un attributo titolo che contenga il testo Auction Item Bid API.

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

Power Apps rimuove tutti gli spazi dal valore di questo attributo e lo utilizza come nome della tua origine dati.

Suggerimento

Ti consigliamo di modificare il valore di questo attributo in un nome con convenzione Pascal come AuctionItemBidAPI e di utilizzarlo come nome della tua connessione personalizzata. In questo modo non ci sarà confusione. Modifica questo valore prima di importare il file OpenAPI per creare il connettore personalizzato.

Nota

Se utilizzi l'opzione Crea da un file vuoto invece di importare un file OpenAPI esistente, PowerApps ti chiederà il nome del connettore personalizzato. Questo nome verrà utilizzato sia come nome del connettore personalizzato che come valore dell'attributo titolo all'interno del file OpenAPI. Assicurati di utilizzare un nome utilizzando la convenzione Pascal ad esempio AuctionItemBidAPI per mantenere le cose coerenti e semplici.

Tabelle dati Excel

PowerApps utilizza DataTable in Microsoft Excel per connettersi ai dati nei fogli di lavoro Excel. Tieni presente questi punti quando crei documenti Excel come origini dati:

  • Dai nomi descrittivi alle tue tabelle dati. Il nome è nell'app Power Apps quando scrivi il codice per connetterti ad essa.
  • Utilizzare una tabella dati per il foglio di lavoro.
  • Assegna lo stesso nome alla tabella dati e al foglio di lavoro.
  • Utilizza nomi di colonna descrittivi nelle tabella dati.
  • Utilizzare la convenzione Pascal. Ogni parola del nome DataTable deve iniziare con una lettera maiuscola, ad esempio EmployeeLeaveRequests.

Oggetti non tipizzati e dinamici

Nomi di variabili

Le convenzioni di denominazione per le variabili nelle app canvas sono importanti per mantenere leggibilità, coerenza e chiarezza nei tuoi progetti Power Apps. Sebbene non venga applicato uno standard rigoroso, l'adozione di una convenzione di denominazione coerente in tutte le app canvas può semplificare la comprensione, l'utilizzo e la gestione delle variabili da parte tua e di altri collaboratori.

  • Utilizza la notazione a cammello, dove la prima lettera di ogni parola è in maiuscolo tranne la prima parola.
  • Scegli nomi significativi e descrittivi che descrivano chiaramente lo scopo o il contenuto della variabile. Evita nomi eccessivamente generici come temp o var1. Utilizza invece nomi descrittivi come userEmail o totalAmount.
  • Considera l'utilizzo di prefissi o suffissi per indicare il tipo di variabile. Ad esempio:
    • strUserName per una variabile testo/stringa
    • numTotalAmount per una variabile numerica
    • boolIsEnabled per una variabile booleana
    • locVarName per variabili locali/variabili di contesto
    • gblVarLoginUser per variabili globali
  • Decidi se le tue variabili devono essere nominate nella forma singolare o plurale e attieniti a tale convenzione. Ad esempio, utilizza in modo coerente userCount o users.
  • Evita di utilizzare parole o nomi riservati che potrebbero entrare in conflitto con funzioni Power Apps o parole chiave. Controlla la documentazione di Power Apps per un elenco di parole riservate.
  • Prendi in considerazione l'utilizzo di prefissi che forniscano il contesto sull'utilizzo o l'ambito della variabile. Ad esempio:
    • frm per le variabili del modulo
    • col per le raccolte
    • var per variabili di uso generale
  • Evita caratteri speciali. Mantieni i nomi alfanumerici ed evita caratteri speciali o spazi. Attieniti a lettere e numeri.

Power Apps consente che le variabili di contesto e le variabili globali condividano gli stessi nomi. Ciò può causare confusione perché le tue formule utilizzano variabili di contesto per impostazione predefinita a meno che non venga utilizzato l'operatore di disambiguazione .

Evita questa situazione seguendo queste convenzioni:

  • Includi un prefisso per le variabili di contesto con loc.
  • Includi un prefisso per le variabili globali con gbl.
  • Il nome dopo il prefisso dovrebbe indicare la finalità o lo scopo della variabile. È possibile utilizzare più parole e non è necessario separarle da caratteri speciali, come spazi o trattini bassi, se la prima lettera di ciascuna parola è in maiuscolo.
  • Utilizza la notazione a cammello. Inizia i nomi delle variabili con un prefisso in lettere minuscole, quindi scrivi in ​​maiuscolo la prima lettera di ogni parola nel nome.

Questi esempi seguono standard e convenzioni:

  • Variabile globale:gblFocusedBorderColor

  • Variabile di contesto:locSuccessMessage

  • Variabile di ambito:scpRadius

Questi esempi non seguono gli standard e sono più difficili da capire:

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

Evita nomi di variabili brevi e criptici come EID. Use EmployeeId invece.

Quando sono presenti molte variabili in un'app, puoi semplicemente digitare il prefisso nella barra delle formule per visualizzare un elenco delle variabili disponibili. Se segui queste linee guida per denominare le variabili, puoi trovarle facilmente nella barra delle formule mentre sviluppi la tua app. In definitiva, questo approccio porta a uno sviluppo delle app più rapido.

Nomi delle raccolte

  • Sii descrittivo rispetto al contenuto della raccolta. Pensa a cosa contiene la raccolta e/o a come viene utilizzata, quindi nominala di conseguenza.
  • Le raccolte dovrebbero essere precedute da col.
  • Il nome dopo il prefisso dovrebbe indicare la finalità o lo scopo della raccolta. È possibile utilizzare più parole e non è necessario separarle da spazi o trattini bassi, se la prima lettera di ciascuna parola è in maiuscolo.
  • Utilizza la notazione a cammello. Inizia i nomi delle raccolte con un prefisso in lettere minuscole, quindi scrivi in ​​maiuscolo la prima lettera di ogni parola nel nome.

Questi esempi seguono le convenzioni sui nomi delle raccolte:

  • colMenuItems
  • colThriveApps

Questi esempi non seguono le convenzioni sui nomi delle raccolte:

  • orderscoll
  • tempCollection

Suggerimento

Quando sono presenti molte raccolte nell'app, puoi semplicemente digitare il prefisso nella barra delle formule per visualizzare un elenco delle raccolte disponibili. Per le variabili, se segui queste linee guida per denominare le raccolte, puoi trovarle facilmente nella barra delle formule mentre sviluppi la tua app. In definitiva, questo approccio porta a uno sviluppo delle app più rapido.

Commenti e documentazione

Mentre scrivi il codice per la tua applicazione, sottolinea l'importanza di commenti completi. Questi commenti non solo servono come guida utile quando si rivisita l'applicazione mesi dopo, ma estendono anche un gesto di gratitudine al prossimo sviluppatore che collabora al progetto.

Esistono due tipi principali di commenti per migliorare la chiarezza del codice: Power Apps supporta due stili di commento: commenti di riga, indicati da doppie barre (//) per commenti a riga singola e commenti in blocco racchiusi all'interno di /* e */ per annotazioni su più righe.

Commenti in riga

Se si aggiunge una doppia barra (//) a qualsiasi riga di codice in PowerApps, il resto della riga (incluso //) viene indicato come commento.

Utilizzare i commenti di riga per chiarire la funzionalità del codice successivo. Possono anche servire a disabilitare temporaneamente una riga di codice, rendendoli utili a scopo di test.

Questo esempio mostra l'uso dei commenti di riga.

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

Blocca i commenti

Il testo racchiuso all'interno di /* e */ viene riconosciuto come commento di blocco. A differenza dei commenti di riga che si applicano a una singola riga, i commenti in blocco possono estendersi su più righe.

I commenti in blocco sono utili per spiegazioni su più righe, ad esempio per documentare l'intestazione di un modulo di codice. Facilitano inoltre la disabilitazione temporanea di più righe di codice durante il test o il debug.

Per un'organizzazione ottimale del codice, è consigliabile aggiungere commenti dopo aver utilizzato la funzione Formatta testo. Ciò è utile se i tuoi commenti precedono un blocco di codice.

/*
    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 funzione Formatta testo segue queste regole per i commenti esistenti:

  1. Se una proprietà inizia con un commento di blocco, ad esso verrà aggiunta la riga di codice successiva.
  2. Se una proprietà inizia con un commento di riga, ad esso non verrà aggiunta la riga di codice successiva. Altrimenti il ​​codice viene commentato.
  3. I commenti di riga e blocco in altre parti della proprietà verranno aggiunti alla riga di codice precedente.

Non preoccuparti di aggiungere troppi commenti o commenti troppo lunghi. Tutti i commenti verranno rimossi quando PowerApps crea il pacchetto dell'app client. Pertanto, non influenzeranno le dimensioni del pacchetto né rallenteranno i tempi di download o caricamento dell'app.

Designer di app moderno con commenti

In Power Apps, è considerata la procedura consigliata per gli autori utilizzare in modo efficace le funzionalità di commento di Power Apps Studio e Finestra di progettazione app moderna.

Per un coinvolgimento ottimale in Power Apps Studio, si consiglia agli autori di aggiungere commenti utilizzando i seguenti metodi:

  1. Fare clic con il pulsante destro del mouse sui puntini di sospensione ("...") di qualsiasi elemento nella visualizzazione ad albero.
  2. Fai clic con il pulsante destro del mouse su un componente nell'area della canvas.
  3. Seleziona il pulsante "Commenti" posizionato nella barra dei comandi nell'angolo in alto a destra dello schermo.

Quando si citano i colleghi nei commenti, si consiglia di utilizzare il simbolo "@" seguito dal loro nome. Ciò richiede un'e-mail di notifica per il collega taggato, garantendo un rapido accesso al commento. Nei casi in cui un utente taggato non ha accesso all'app, al produttore viene richiesto di condividere l'app con lui.

Screenshot di un'app per le spese che mostra una persona @ menzionata nel commento

Identificazione e formattazione

In Power Apps, il rientro e la formattazione sono fondamentali per mantenere una struttura chiara e organizzata nella tua app. Seguendo le procedure consigliate si migliora la leggibilità delle formule e dei controlli.

Barra della formula

Rientro

Sebbene Power Apps non imponga un rientro rigoroso, puoi utilizzare gli spazi per separare visivamente le diverse sezioni delle formule. Premi la barra spaziatrice più volte per creare un effetto di rientro.

Interruzioni di riga

Puoi suddividere formule lunghe in più righe per migliorarne la leggibilità. Premi Invio per creare un'interruzione di riga nella barra della formula.

Utilizza il comando Formatta testo

Il comando "Formatta testo" nella barra della formula è progettato per applicare rientro, spaziatura e interruzioni di riga al tuo codice Power Apps. Utilizza il comando "Formatta testo" per stabilire uno stile di codifica uniforme nell'intera app canvas, garantendo un processo di sviluppo più efficiente e resistente agli errori.

Screenshot di Power Apps Studio con il comando Formatta testo evidenziato

Passaggio successivo

Ottimizzazione del codice