Legibilidade do código

Convenções de nomenclatura

Convenções de nomenclatura gerais

Esta seção descreve as convenções de nomenclatura "camel case" e "Pascal case". Se já estiver familiarizado com esses termos, pode saltar em frente.

Camelcase

Você deve usar camel case para controles e variáveis. Camel case começa com um prefixo em letra minúscula, remove todos os espaços dos nomes de objetos ou variáveis e capitaliza a primeira letra de cada palavra após a primeira. Por exemplo, um controlo de entrada de texto pode ser denominado txtUserEmailAddress.

Caso Pascal

Deve utilizar o caso Pascal para origens de dados. O caso Pascal é, por vezes, referido como "caso de letras minúsculas e maiúsculas misturadas superior". Tal como letras minúsculas e maiúsculas misturadas, remove todos os espaços e colocar em maiúscula a primeira letra das palavras. No entanto, ao contrário de camel case, o caso Pascal também coloca a primeira palavra em letra maiúscula. Por exemplo, a origem de dados comum no PowerApps é o conector de Utilizadores do Microsoft Office 365, chamado de Office365Users no seu código.

Nomes de ecrã

Os nomes de ecrã devem refletir a finalidade do ecrã, para que seja mais fácil navegar através de aplicações complexas no Power Apps Studio.

O que é menos óbvio é que os nomes de tela são lidos em voz alta pelos leitores de tela, que são necessários para usuários que têm necessidades de acessibilidade visual. Portanto, é imperativo que utilize linguagem simples para nomear os seus ecrãs e que os nomes incluam espaços e nenhuma abreviatura. Além disso, recomendamos que termine o nome com a palavra "Ecrã", para que o contexto seja compreendido quando o nome é anunciado.

Eis alguns bons exemplos:

• Home_Screen ou Home Screen
• Search_Screen ou Search Screen

Estes nomes de ecrã de exemplo são menos compreensíveis:

• Home
• LoaderScreen
• EmpProfDetails
• Thrive Help

Nomes de controlos

Todos os nomes de controlo na tela devem utilizar camel case. Devem começar com um descritor de tipo de três caracteres, seguido da finalidade do controlo. Esta abordagem ajuda a identificar o tipo de controlo e facilita a criação de fórmulas e a pesquisa. Por exemplo, lblUserName indica que o controlo é uma etiqueta.

A tabela seguinte mostra as abreviaturas dos controlos comuns.

Nome do controlo	Abreviatura
Distintivo	bdg
Botão	btn
Controlo de câmara	cam
Tela	can
Cartão	crd
Gráficos	CHR
CaixaVerificação	CHK
Coleção	col
Caixa de combinação	CMB
Componente	cmp
Contentor	con
Dates	DTE
Lista pendente	DRP
Formulário	FRM
Galeria	gal
Agrupar	grp
Cabeçalho	HDR
Texto html	htm
Ícone	ico
Imagem	img
Botão de Informações	Informações do
Etiqueta	lbl
Associar	lnk
Caixa de listagem	lst
Microfone	mic
Microsoft Stream	str
Forma da secção da página	seg
Entrada de Caneta	pen
Mosaico do Power BI	pbi
Barra de Progresso	pbar
Rating	rtg
Editor de texto formatado	rte
Formas (retângulo, círculo, etc.)	SHP
Controlo de deslize	SLD
Lista de Separadores	TBL
Table	TBL
Introdução de texto	txt
Temporizador	TMR
Botão de alternar	tgl
Video	vid

A lista detalhada de controlos e as respetivas propriedades estão descritas em Referência de controlos.

Nota

Os nomes de controlo têm de ser exclusivos numa aplicação. Se um controlo for reutilizado em vários ecrãs, o nome curto do ecrã deve ter um sufixo. Por exemplo, galBottomNavMenuHS, onde "HS" significa "Home Screen" (Ecrã Base). Esta abordagem facilita referenciar o controlo em fórmulas entre ecrãs.

Eis exemplos maus:

• zipcode
• Next

Quando nomeia consistentemente os seus controlos, a sua aplicação é mais limpa na vista de navegação e o seu código também é mais limpo.

Nomes da origem de dados

Quando adiciona uma origem de dados à aplicação, o nome não pode ser alterado na aplicação Power Apps. O nome é herdado do conector de origem ou entidades de dados que são derivadas da ligação.

Seguem-se alguns exemplos:

• Nome herdado do conector de origem: O conector de Utilizadores do Office 365 é chamado de Office365Users no seu código.
• Entidades de dados derivadas da ligação: Uma lista da Microsoft SharePoint nomeada Employees é devolvida do SharePoint conector. Por isso, o nome da origem de dados no seu código é Employees. A mesma aplicação Power Apps também pode utilizar o mesmo conector do SharePoint para aceder a uma lista do SharePoint denominada Contractors. Neste caso, o nome da origem de dados no código é Contractors.

Para obter mais informações sobre conectores e ligações, consulte Descrição geral de conectores de aplicações de tela para Power Apps.

Conectores de ação padrão

Nos conectores de ação Padrão que expõem funções, como o LinkedIn, o nome da origem de dados e as respetivas operações utilizam o caso Pascal. Por exemplo, a origem de dados do LinkedIn é denominada LinkedIn e tem uma operação nomeada ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Conectores personalizados

Conectores personalizados utilizados para ligar a interfaces de programação de aplicações (APIs) personalizadas, tais como serviços ou APIs de linha de negócio que a sua empresa criou. Podem ser criadas por qualquer criador no seu ambiente. Recomendamos o caso Pascal para o nome da origem de dados e respetivas operações. Apenas esteja ciente de que o nome do conector personalizado e a forma como aparece no PowerApps podem diferir.

Considere este exemplo de um conector personalizado nomeado MS Auction Item Bid API.

No entanto, quando cria uma ligação a partir deste conector e a adiciona à sua aplicação PowerApps como uma origem de dados, esta aparece como AuctionItemBidAPI.

Para descobrir a razão, pode procurar um atributo title no interior do OpenAPI ficheiro que contenha o texto Auction Item Bid API.

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

O Power Apps remove todos os espaços deste valor de atributo e utiliza-o como o nome da sua origem de dados.

Sugestão

Recomendamos que altere o valor deste atributo para um nome com caixa Pascal como AuctionItemBidAPI e utilize-o como o nome da sua ligação personalizada. Dessa forma, não haverá confusão. Altere este valor antes de importar o OpenAPI ficheiro para criar o conector personalizado.

Nota

Se utilizar a opção Criar a partir de em branco, em vez de importar um ficheiro OpenAPI existente, o PowerApps irá pedir-lhe o nome do conector personalizado. Este nome será utilizado como o nome do conector personalizado e como o valor do atributo do título dentro do OpenAPI ficheiro. Certifique-se de que utiliza um nome com caso Pascal, como AuctionItemBidAPI para manter as coisas consistentes e simples.

Tabelas de Dados do Excel

O PowerApps utiliza Tabelas de Dados no Microsoft Excel para se ligar a dados em folhas de cálculo do Excel. Tenha em mente estes pontos quando criar documentos do Excel como origens de dados:

• Dê aos seus DataTables nomes descritivos. O nome está na aplicação Power Apps quando escreve o código para se ligar a ela.
• Use uma DataTable por planilha.
• Dê o mesmo nome à Tabela de Dados e à folha de cálculo.
• Use nomes de coluna descritivos nas DataTables.
• Utilize caso Pascal. Cada palavra do nome da Tabela de Dados deve começar com uma letra maiúscula, como EmployeeLeaveRequests.

Objetos dinâmicos e sem tipo

Nomes de variável

As convenções de nomenclatura para variáveis em aplicações de tela são importantes para manter a legibilidade, a consistência e a clareza nos seus projetos do Power Apps. Embora nenhum padrão estrito seja imposto, adotar uma convenção de nomenclatura consistente em toda a sua aplicação de tela pode facilitar para si e outros colaboradores compreender, usar e gerir as variáveis.

• Use camel case, onde a primeira letra de cada palavra é maiúscula, exceto a primeira palavra.
• Escolha nomes significativos e descritivos que descrevam claramente a finalidade ou o conteúdo da variável. Evite nomes demasiado genéricos como temp ou var1. Em vez disso, use nomes descritivos como userEmail ou totalAmount.
• Considere utilizar prefixos ou sufixos para indicar o tipo de variável. Por exemplo:
  • strUserName para uma variável de text/cadeia
  • numTotalAmount para uma variável numérica
  • boolIsEnabled Para uma variável booleana
  • locVarName para variáveis locais/variáveis de contexto
  • gblVarLoginUser para variáveis globais
• Decida se as variáveis devem ser nomeadas no singular ou no plural e mantenha essa convenção. Por exemplo, utilize consistentemente userCount ou users.
• Evite utilizar nomes ou palavras reservadas que possam entrar em conflito com funções ou palavras-chave do Power Apps. Consulte a Power Apps documentação para obter uma lista de palavras reservadas.
• Considere utilizar prefixos que forneçam contexto sobre a utilização ou o âmbito da variável. Por exemplo:
  • frm para variáveis de formulário
  • col para coleções
  • var para variáveis de finalidade geral
• Evite carateres especiais. Mantenha os nomes alfanuméricos e evite carateres especiais ou espaços. Utilize apenas letras e números.

O Power Apps permite que as variáveis de contexto e as variáveis globais partilhem os mesmos nomes. Isto pode causar confusão porque as suas fórmulas utilizam variáveis de contexto por predefinição, a menos que seja utilizado o operador de desambiguação.

Evite esta situação seguindo estas convenções:

• Prefixe as variáveis de contexto com loc.
• Prefixe as variáveis globais com gbl.
• O nome após o prefixo deve indicar a intenção/finalidade da variável. Várias palavras podem ser usadas e não precisam ser separadas por nenhum caractere especial, como espaços ou sublinhados, se a primeira letra de cada palavra estiver em maiúsculas.
• Use Camel case. Comece os nomes das variáveis com um prefixo em letras minúsculas e, em seguida, coloque a primeira letra de cada palavra no nome em maiúscula.

Estes exemplos seguem normas e convenções:

• Variável global:gblFocusedBorderColor

• Variável de contexto:locSuccessMessage

• Variável de âmbito:scpRadius

Estes exemplos não seguem os padrões e são mais difíceis de entender:

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

Evite nomes de variáveis curtos e enigmáticos, como EID. Use EmployeeId alternativamente.

Quando existem muitas variáveis numa aplicação, basta escrever o prefixo na barra de fórmulas para ver uma lista das variáveis disponíveis. Se seguir estas orientações para nomear as suas variáveis, poderá encontrá-las facilmente na barra de fórmulas à medida que desenvolve a sua aplicação. Em última análise, esta abordagem leva a um desenvolvimento mais rápido da aplicação.

Nomes de coleções

• Seja descritivo do conteúdo da coleção. Pense no que a coleção contém e/ou como é usada e, em seguida, nomeie-a de acordo.
• As coleções devem ser prefixadas com col.
• O nome após o prefixo deve indicar a intenção ou finalidade da coleção. Podem ser utilizadas várias palavras, sem a necessidade de espaços nem sublinhados, desde que a primeira letra de cada palavra esteja em letra maiúscula.
• Use Camel case. Comece os nomes da coleção com um prefixo col minúsculo e, em seguida, coloque em maiúscula a primeira letra de cada palavra no nome.

Estes exemplos seguem as convenções de nomes de coleções:

• colMenuItems
• colThriveApps

Estes exemplos não seguem as convenções de nomes de coleções:

• orderscoll
• tempCollection

Sugestão

Quando existem muitas coleções na aplicação, basta escrever o prefixo na barra de fórmulas para ver uma lista das coleções disponíveis. Quanto às variáveis, se seguir estas orientações para nomear as suas coleções, poderá encontrá-las muito facilmente na barra de fórmulas à medida que desenvolve a sua aplicação. Em última análise, esta abordagem leva a um desenvolvimento mais rápido da aplicação.

Comentários e documentação

Ao escrever código para seu aplicativo, enfatize a importância de comentários abrangentes. Esses comentários não só servem como um guia útil quando você revisita o aplicativo meses depois, mas também estendem um gesto de gratidão ao próximo desenvolvedor que colabora no projeto.

Existem dois tipos principais de comentários para melhorar a clareza do código: o Power Apps suporta dois estilos de comentário: comentários de linha, indicados por barras duplas (//) para observações de linha única e comentários de bloco incluídos dentro de /* e de */ para anotações com várias linhas.

Comentários de linha

Adicionar uma barra dupla (//) a qualquer linha de código no PowerApps designa o resto da linha (incluindo a //) como um comentário.

Utilize comentários de linha para elucidar a funcionalidade do código subsequente. Também podem servir para desativar temporariamente uma linha de código, tornando-os úteis para fins de teste.

Este exemplo mostra a utilização de comentários de linha.

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

Comentários de bloco

O texto dentro de /* e de */ é reconhecido como um comentário em bloco. Ao contrário dos comentários de linha que se aplicam a uma única linha, os comentários de bloco podem abranger várias linhas.

Os comentários de bloco são úteis para explicações com várias linhas, como documentar um cabeçalho de módulo de código. Também facilitam a desativação temporária de várias linhas de código durante os testes ou a depuração.

Para organização de código ideal, é aconselhável adicionar comentários depois de utilizar a caraterística Formatar Texto. Isto é benéfico se os seus comentários precederem um bloco de código.

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

A funcionalidade Formatar Texto segue estas regras para comentários existentes:

1. Se uma propriedade começar com um comentário em bloco, a próxima linha de código será anexada a ela.
2. Se uma propriedade começar com um comentário de linha, a próxima linha de código não será anexada a ela. Caso contrário, o código é deixado de fora.
3. Os comentários de linha e bloco em outro lugar da propriedade serão anexados à linha de código anterior.

Não se preocupe em adicionar muitos comentários ou comentários muito longos. Todos os comentários são removidos quando o PowerApps cria o pacote de aplicações cliente. Portanto, não afetarão o tamanho do pacote nem diminuirão os tempos de download ou carregamento do aplicativo.

Estruturador de aplicações moderno com comentários

No Power Apps, é considerada a melhor prática para os criadores utilizarem eficazmente caraterísticas de comentários no Power Apps Studio e no estruturador de aplicações Moderno.

Para uma interação otimizada no Power Apps Studio, os criadores são aconselhados a adicionar comentários utilizando os seguintes métodos:

1. Clique com o botão direito do rato nas reticências ("...") de qualquer item na Vista de Árvore.
2. Clique com o botão direito do rato num componente na área da tela.
3. Selecione o botão "Comentários" localizado na barra de comando no canto superior direito da tela.

Ao mencionar colegas em comentários, recomenda-se que utilize o símbolo "@" seguido do nome deles. Isto aciona um e-mail de notificação para o colega identificado, o que garante um acesso rápido ao comentário. Nos casos em que um utilizador identificado não tem acesso à aplicação, é pedido ao criador que partilhe a aplicação com ele.

Avanço e formatação

No Power Apps, o avanço e a formatação são cruciais para manter uma estrutura clara e organizada na sua aplicação. Seguir as melhores práticas melhora a legibilidade das suas fórmulas e controlos.

Barra de fórmulas

Recuo

Embora o Power Apps não imponha um avanço estrito, pode utilizar espaços para separar visualmente diferentes secções das suas fórmulas. Pressione a barra de espaço várias vezes para criar um efeito de avanço.

Quebras de linha

Pode dividir fórmulas longas em várias linhas para melhorar a legibilidade. Prima Enter para criar uma quebra de linha na barra de fórmulas.

Utilizar o comando Formatar texto

O comando "Formatar Texto" na barra de fórmulas foi concebido para aplicar avanço, espaçamento e quebras de linha ao seu Power Apps código. Utilize o comando "Formatar Texto" para estabelecer um estilo de codificação uniforme em toda a aplicação de tela, garantindo um processo de programação mais eficiente e resistente a erros.

Próximo passo

Otimização do código