Koodin luettavuus

Nimeämiskäytännöt

Yleiset nimeämiskäytännöt

Tässä osassa käsitellään CamelCase- ja PascalCase-tyylisiä nimeämiskäytäntöjä. Jos nämä termit ovat tuttuja, kyseiset kohdat voidaan ohittaa.

CamelCase-tyyli

CamelCase-tyyliä kannattaa käyttää ohjausobjekteissa ja muuttujissa. CamelCase-tyylin alussa on pienellä kirjaimella kirjoitettu etuliite, minkä lisäksi kaikki välilyönnit poistetaan objektin tai muuttujan nimestä ja kunkin ensimmäisen sanan jälkeisen sanan ensimmäinen kirjain kirjoitetaan isoin kirjaimin. Esimerkiksi tekstisyöteohjausobjektin nimi voisi olla txtUserEmailAddress.

PascalCase-tyyli

PascalCase-tyyliä kannattaa käyttää tietolähteissä. PascalCasea kutsutaan joskus ison kirjaimen CamelCaseksi. CamelCasen tapaan sitä käytettäessä poistetaan kaikki välilyönnit ja kirjoitetaan sanojen ensimmäiset kirjaimet isolla. CamelCase-tyylistä poiketen PascalCase-tyylissä myös ensimmäisen sana kirjoitetaan isolla kirjaimella. Esimerkki: PowerAppsin yleinen tietolähde on Microsoft Office 365 -käyttäjien yhdistin, joka nimenä on koodissa Office365Users.

Näytön nimet

Näytön nimien on ilmaistava näytön tarkoitus, mikä helpottaa monimutkaisissa sovelluksissa siirtymistä Power Apps Studiossa.

Yhtä selvää ei sen ole se, että näytön lukuohjelmat lukevat näytön nimet ääneen, mikä on välttämätöntä näkövammaisten käyttäjien kannalta. Niinpä onkin välttämätöntä, että näyttöjen nimeämisessä käytetään yksinkertaista kieltä ja että nimissä on välilyöntejä muttei lyhenteitä. Lisäksi on suositeltavaa, että nimi päättyy Näyttö-sanaan, mikä helpottaa kontekstin ymmärtämistä, kun nimi ilmoitetaan.

Hyviä esimerkkejä:

• Home_Screen tai Home Screen
• Search_Screen tai Search Screen

Nämä esimerkkinäyttönimet ovat vähemmän ymmärrettäviä:

• Home
• LoaderScreen
• EmpProfDetails
• Thrive Help

Ohjausobjektien nimet

Kaikissa kaavion ohjausobjektien nimissä on käytettä CamelCase-tyyliä. Niissä on oltava ensimmäisenä kolmikirjaiminen tyyppikuvaus, jota seuraa ohjausobjektin tarkoitus. Tämä menetelmä auttaa tunnistamaan ohjausobjektin tyypin, minkä lisäksi se helpottaa kaavojen ja haun muodostamista. Esimerkiksi lblUserName ilmaisee, että ohjausobjektin on selite.

Seuraavassa taulukko on yleisten ohjausobjektien lyhenteet.

Ohjausobjektin nimi	Lyhenne
Merkki	bdg
Button	btn
Kamera-ohjausobjekti	cam
Pohja	can
Card	crd
Kaaviot	chr
Valintaruutu	chk
Kokoelma	col
Yhdistelmäruutu	cmb
Osa	cmp
Säilö	con
Päivämäärät	dte
Avattava	drp
Lomake	frm
Galleria	gal
Ryhmittele	grp
Otsikko	hdr
Html-teksti	htm
Icon	ico
Kuva	img
Tietopainike	-tiedot
Otsake	lbl
Linkki	lnk
Luetteloruutu	lst
Mikrofoni	mikrofoni
Microsoft Stream	str
Sivu-osan muoto	sek
Kynäsyöte	pen
Power BI -ruutu	pbi
Tilanneilmaisin	pbar
Rating	rtg
RTF-editori	rte
Muodot (kuten suorakulmio ja ympyrä)	shp
Liukusäädin	sld
Välilehtiluettelo	tbl
Table	tbl
Tekstisyöte	txt
Ajastin	tmr
Vaihtopainike	tgl
Video	vid

Yksityiskohtainen luettelo ohjausobjekteista ja niiden ominaisuuksista on kohdassa Lisätietoja ohjausobjekteista.

Muistiinpano

Ohjausobjektien nimien on oltava yksilöiviä koko sovelluksessa. Jos ohjausobjektia käytetään uudelleen useissa näytössä, lyhyessä näytön nimessä on oltava jälkiliite. Esimerkiksi galBottomNavMenuHS, jossa HS tarkoittaa aloitusnäyttöä. Tämä lähestymistapa helpottaa ohjausobjektiin viittaamista eri näyttöjen kaavoissa.

Esimerkkejä epäonnistuneista nimistä:

• zipcode
• Next

Ohjausobjektien yhdenmukainen nimeäminen selkeyttää sovelluksen hahmottamista siirtymisnäkymässä, minkä lisäksi se selkeyttää myös koodia.

Tietolähteiden nimet

Kun tietolähde lisätään sovellukseen, nimeä ei voi muuttaa Power Apps -sovelluksessa. Nimi peritään lähdeyhdistimistä tai yhteydestä johdettavista tietoentiteeteistä.

Seuraavassa on joitakin esimerkkejä.

• Lähdeyhdistimestä peritty nimi: Office 365:n käyttäjät -yhdistin on koodissa muodossa Office365Users.
• Yhteydestä johdetut tietoentiteetit:Employees-niminen Microsoft SharePoint -luettelo palautetaan SharePoint-yhdistimestä. Tämän vuoksi tietolähteen nimi koodissa on Employees. Sama Power Apps -sovellus voi käyttää myös samaa SharePoint-yhdistintä käyttämään Contractors-nimistä SharePoint-luetteloa. Siinä tapauksessa tietolähteen nimi koodissa on Contractors.

Lisätietoja yhdistimistä ja yhteyksistä on kohdassa Power Appsin pohjaan perustuvan sovelluksen yhdistimien yleiskatsaus.

Vakiotoiminnon yhdistimet

Toimintoja, kuten LinkedInin, näyttävissä vakiotoimintojen yhdistimissä tietolähteen nimessä ja sen toiminnoissa käytetään PascalCase-tyyliä. Esimerkiksi LinkedIn-tietolähteen nimenä on LinkedIn ja sen toiminnon nimenä ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Mukautetut liittimet

Mukautettuja yhdistimiä käytetään yhdistämään mukautetut ohjelmointirajapinnat, kuten yrityksen luomat palvelujen ohjelmointirajapinnat ja toimialakohtaiset ohjelmointirajapinnat. Kuka tahansa tekijä voi luoda niitä ympäristössä. Tietolähteen nimessä ja sen toiminnossa suositellaan PascalCase-tyylin käyttämistä. On kuitenkin muistettava, että mukautetun yhdistimen nimi ja sen näkyminen PowerAppsissa voi vaihdella.

Esimerkkinä tästä on MS Auction Item Bid API -niminen mukautettu yhdistin.

Mutta kun tästä yhdistimestä luodaan yhteys ja se lisätään PowerApps -sovellukseen tietolähteenä, yhdistin näkyy muodossa AuctionItemBidAPI.

Syy tähän selviää tarkastelemassa tekstin Auction Item Bid API sisältävän otsikkomääritteen OpenAPI-tiedostoa.

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

Power Apps poistaa kaikki välilyönnit tästä määritearvosta ja käyttää sitä tietolähteen nimenä.

Vinkki

Tämän määritteen arvo kannattaakin muuttaa PascalCase-tyyliksi nimeksi, kuten AuctionItemBidAPI, ja sitä mukautetun yhteyden nimenä. Tällä tavoin vältetään sekaannukset. Tämä arvo on muutettava, ennen kuin OpenAPI-tiedosto tuodaan mukautetun yhdistimen luontia varten.

Muistiinpano

Jos käytössä on Luo tyhjästä -vaihtoehto aiemmin luodun OpenAPI-tiedoston tuonnin sijaan, PowerApps kysyy mukautetun yhdistimen nimeä. Tätä nimeä käytetään sekä mukautetun yhdistimen nimenä että otsikkomääritteen arvona OpenAPI-tiedostossa. Yhdenmukaisuus ja yksinkertaisuus voidaan varmistaa muistamalla käyttää PascalCase-tyylin mukaista nimeä, kuten AuctionItemBidAPI.

Excelin arvotaulukot

PowerApps käyttää Microsoft Excelin arvotaulukoita muodostamaan yhteys Excelin laskentataulukoiden tietoihin. Seuraavat seikat kannattaa muistaa, kun Excel-asiakirjoja luodaan tietolähteiksi:

• Arvotaulukoille on annettava kuvailevat nimet. Nimi on Power Apps -sovelluksessa, kun siihen yhdistävä koodi kirjoitetaan.
• Kussakin laskentataulukossa käytetään yhtä arvotaulukkoa.
• Arvotaulukolle ja laskentataulukolle annetaan sama nimi.
• Kuvailevien sarakenimien käyttäminen arvotaulukoissa.
• PascalCase-tyylin käyttäminen. Arvotaulukon nimen kunkin sanan ensimmäinen kirjain on iso, kuten EmployeeLeaveRequests.

Muuttujan nimet

Pohjaan perustuvien sovellusten muuttujien nimeämiskäytännöt ovat tärkeitä luettavuuden, yhdenmukaisuuden ja selkeyden säilyttämisen kannalta Power Apps -projekteissa. Vaikka mitään tiukkaa standardia ei vaadita, yhdenmukaisen nimeämiskäytännön käyttöönotto pohjaan perustuvassa sovelluksessa voi helpottaa muuttujien ymmärtämistä, käyttöä ja hallintaa sinulle ja muille yhteistyötä tekeville.

• CamelCase-tyylin on syytä käyttää. Tässä tyylissä ensimmäistä sanaa lukuun ottamatta kunkin sanan ensimmäinen kirjain kirjoitetaan isolla.
• Valittavien nimien on oltava merkityksellisiä ja kuvailevia siten, että ne ilmaisevat muuttajan tarkoituksen tai sisällön selkeästi. Liian yleisten nimien, kuten temp tai var1, välttäminen. Sen sijaan kannattaa käyttää kuvailevia nimiä, kuten userEmail tai totalAmount.
• Muuttujan tyypin ilmaisemista etu- tai jälkiliitteen avulla kannattaa harkita. Esimerkiksi:
  • strUserName, jos kyseessä on teksti- tai merkkijonomuuttuja
  • numTotalAmount, jos kyseessä on numeromuuttuja
  • boolIsEnabled, jos kyseessä on totuusarvomuuttuja
  • locVarName jos kyseessä on paikalliset muuttujat tai kontekstimuuttujat
  • gblVarLoginUser, jos kyseessä on yleiset muuttujat
• Lisäksi on päätettävä, on muuttujan nimi yksikössä vai monikossa, ja päätettyä käytäntöä on käytettävä johdonmukaisesti. On siis käytettävä johdonmukaisesti esimerkiksi muotoa userCount tai users.
• Varattujen sanojen tai sellaisten sanojen, jotka voivat olla ristiriidassa Power Appsin funktioiden tai avainsanojen kanssa, käyttöä on vältettävä. Varatut sanat voi tarkistaa Power Appsin ohjeissa olevasta luettelosta.
• Kannattaa harkita muuttujan käyttö- tai vaikutusaluekontekstin ilmaisevien etuliitteiden käyttöä. Esimerkki:
  • frm, jos kyse on muotomuuttujista
  • col, jos kyse on kokoelmista
  • var, jos kyse on yleisistä muuttujista
• Erikoismerkkien käyttöä on vältettävä. Nimissä kannattaa käyttää aakkosnumeerisia merkkejä sekä välttää erikoismerkkejä ja välilyöntejä. Nimessä käytetään siis kirjaimia ja numeroita.

Power Apps mahdollistaa saman nimen käyttämisen kontekstimuuttujille ja yleisille muuttujille. Tämä voi aiheuttaa sekaannusta, sillä kaavat käyttävät oletusarvoisesti kontekstimuuttujia ellei käytössä ole selvitysoperaattori.

Tämä tilanne voidaan välttää seuraavien käytäntöjen avulla:

• loc-etuliitteen käyttäminen kontekstimuuttujissa.
• gbl-etuliitteen käyttäminen yleisissä muuttujissa.
• Etuliitteen jälkeisen nimen on ilmaistava muuttujan tarkoitus. Sanoja voi olla useita eikä niitä tarvitse erottaa erikoismerkeillä, kuten välilyönneillä tai alaviivoilla, jos jokainen sana kirjoitetaan isolla alkukirjaimella.
• CamelCase-tyylin käyttäminen. Ensimmäisenä muuttujan nimessä on pienellä kirjoitettu etuliite, jonka jälkeen nimen jokaisen sana kirjoitetaan isolla alkukirjaimella.

Seuraavat esimerkit ovat standardien ja käytäntöjen mukaisia:

• Yleinen muuttuja:gblFocusedBorderColor

• Kontekstimuuttuja:locSuccessMessage

• Vaikutusalueen muuttuja:scpRadius

Nämä esimerkit eivät noudata standardeja, ja niitä on vaikeampi ymmärtää:

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

Lyhyiden ja epäselvien muuttujanimien, kuten EID, välttäminen. Parempi nimi on Use EmployeeId.

Jos sovelluksessa on paljon muuttujia, käytettävissä olevia muuttujia voi tarkastella kirjoittamalla etuliitteen kaavariville. Jos muuttujat nimetään näiden ohjeiden mukaisesti, ne on helppo etsiä kaavarivillä sovellusta kehitettäessä. Viime kädessä tämän menetelmän käyttäminen nopeuttaa sovelluksen kehittämistä.

Kokoelmien nimet

• Kokoelman sisältöä kannattaa kuvailla. Kokoelman sisältöä ja/tai sen käyttöä kannattaa pohtia, ja nimetä kokoelma sitten sen mukaisesti.
• Kokoelmissa on käytettävä etuliitettä col.
• Etuliitteen jälkeisen nimen on ilmaistava kokoelman tarkoitus. Sanoja voi olla useita eikä niitä tarvitse erottaa välilyönneillä tai alaviivoilla, jos jokainen sana kirjoitetaan isolla alkukirjaimella.
• CamelCase-tyylin käyttäminen. Ensimmäisenä kokoelman nimessä on pienellä kirjoitettu col-etuliite, jonka jälkeen nimen jokainen sana kirjoitetaan isolla alkukirjaimella.

Seuraavissa esimerkeissä käytetään kokoelman nimeämiskäytäntöjä:

• colMenuItems
• colThriveApps

Seuraavissa esimerkeissä ei käytetä kokoelman nimeämiskäytäntöjä:

• orderscoll
• tempCollection

Vinkki

Jos sovelluksessa on paljon kokoelmia, käytettävissä olevia kokoelmia voi tarkastella kirjoittamalla etuliitteen kaavariville. Jos nimeät kokoelmasi näiden ohjeiden mukaisesti, löydät muuttujat helposti kaavariviltä, kun kehität sovellustasi. Viime kädessä tämän menetelmän käyttäminen nopeuttaa sovelluksen kehittämistä.

Kommentit ja ohjeet

Kun kirjoitat koodia sovelluksellesi, keskity selkeiden kommenttien lisäämiseen. Kommentit auttavat sinua ymmärtämään koodisi myöhemmin ja helpottavat seuraavan kehittäjän työskentelyä projektin parissa.

Power Apps tukee kahta kommenttityyliä koodin selkeyttämiseksi: rivikommentit, joissa käytetään kaksinkertaisia vinoviivoja (//) yksirivisiä muistiinpanoja varten, ja lohkokommentit, joissa käytetään merkkejä /* ja */ monirivisiä muistiinpanoja varten.

Rivikommentit

Lisää kaksinkertainen vinoviiva (//) mille tahansa koodiriville Power Appsissa, jotta rivin loppuosasta tulee kommentti.

Käytä rivikommentteja selittääksesi, mitä seuraava koodirivi tekee. Niiden avulla voit myös poistaa koodirivin tilapäisesti käytöstä testausta varten.

Tässä on esimerkki rivikommentista.

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

Lohkokommentit

Teksti merkkien /* ja */ välillä on lohkokommentti. Lohkokommentit voivat kattaa useita rivejä, toisin kuin rivikommentit, jotka kattavat vain yhden rivin.

Käytä estokommentteja pidempiin selityksiin, kuten koodimoduulin otsikon dokumentointiin. Niiden avulla voit myös poistaa tilapäisesti käytöstä useita koodirivejä testauksen tai virheenkorjauksen aikana.

Jos haluat parantaa koodin organisointia, lisää kommentteja Muotoile tekstiä -ominaisuuden käytön jälkeen. Tämä auttaa, jos kommenttisi tulevat ennen koodilohkoa.

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

Muotoile tekstiä -toiminto noudattaa seuraavia sääntöjä kommenteissa:

1. Jos ominaisuus alkaa lohkokommentilla, siihen lisätään seuraava koodirivi.
2. Jos ominaisuus alkaa rivikommentilla, siihen ei lisätä seuraavaa koodiriviä. Muussa tapauksessa koodista tulee kommentti.
3. Muualla ominaisuudessa olevat rivi- ja lohkokommentit lisätään edelliselle koodiriville.

Älä huolehdi liian monien tai liian pitkien kommenttien lisäämisestä. Power Apps poistaa kaikki kommentit, kun se luo asiakassovelluspaketin, joten kommentit eivät vaikuta paketin kokoon tai hidasta sovellusten lataamista tai latausaikoja.

Moderni sovellusten suunnitteluohjelma ja kommentit

Power Appsissa kannattaa käyttää kommentointiominaisuuksia sekä Power Apps Studiossa että modernissa sovellusten suunnitteluohjelmassa.

Voit lisätä kommentteja Power Apps Studiossa seuraavilla menetelmillä:

1. Kohteen kolmen pisteen (...) napsauttaminen hiiren kakkospainikkeella puunäkymässä.
2. Komponentin napsauttaminen hiiren kakkospainikkeella kaavioalueella.
3. Kommentit-painikkeen valitseminen näytön oikeassa kulmassa olevassa komentopalkissa.

Kun mainitset työtoverin kommentissa, käytä @-merkkiä ja hänen nimeään. Tämä lähettää ilmoitusviestin tunnisteella merkitylle henkilölle. Jos tunnuksella merkityllä käyttäjällä ei ole sovelluksen käyttöoikeuksia, Power Apps kehottaa jakamaan sovelluksen heidän kanssaan.

Sisennyt ja muotoilu

Power Appsissa sisennys ja muotoilu auttavat pitämään sovelluksen selkeänä ja järjestyksessä. Parhaiden käytäntöjen noudattaminen helpottaa kaavojen ja ohjausobjektien lukemista.

Kaavarivi

Sisennys

Power Apps ei valvo tiukkaa sisennystä, mutta voit käyttää välilyöntejä kaavojen eri osien erottamiseen. Luo sisennys painamalla välilyöntiä useita kertoja.

Rivinvaihdot

Jaa pitkät kaavat useille riveille, jotta niitä on helpompi lukea. Paina Enter lisätäksesi rivinvaihdon kaavariville.

Muotoile tekstiä -komennon käyttäminen

Kaavarivin Muotoile teksti -komento lisää Power Apps -koodiin sisennyksen, välit ja rivinvaihdot. Käytä Muotoile teksti -komentoa pitämään pohjaan perustuvan sovelluksen koodaustyylin johdonmukaisena ja ehkäisemään virheitä.

Seuraava vaihe

Koodin optimointi