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.

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

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.

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.

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

Comentários e documentação

Quando escrever código para a sua aplicação, foque-se em adicionar comentários claros. Comentários ajudam a compreender o seu código mais tarde e facilitam o trabalho do próximo programador no projeto.

O Power Apps suporta dois estilos de comentário para tornar o seu código mais claro: comentários de linha, que usam barras duplas (//) para notas de uma linha, e comentários de bloco, que usam /* e */ para notas de várias linhas.

Comentários de linha

Adicione uma barra dupla (//) em qualquer linha de código no Power Apps para tornar o resto da linha um comentário.

Use comentários de linha para explicar o que a linha seguinte de código faz. Também pode usá-los para desativar temporariamente uma linha de código para teste.

Eis um exemplo de um comentário 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 entre /* e */ é um comentário em bloco. Os comentários em bloco podem cobrir várias linhas, ao contrário dos comentários de linha, que apenas cobrem uma linha.

Use comentários em bloco para explicações mais longas, como documentar um cabeçalho de módulo de código. Também pode usá-los para desativar temporariamente várias linhas de código durante o teste ou a depuração.

Para uma melhor organização do código, adicione comentários depois de usar a caraterística Formatar Texto. Isto ajuda se os seus comentários vierem antes de 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 caraterística Formatar Texto segue estas regras para comentários:

1. Se uma propriedade começar com um comentário em bloco, a linha de código seguinte será adicionada a ele.
2. Se uma propriedade começar com um comentário de linha, a linha de código seguinte não será adicionada a ele. Caso contrário, o código é deixado de fora.
3. Os comentários de linha e em bloco noutras partes da propriedade são adicionados à linha de código anterior.

Não se preocupe em adicionar comentários muito longos ou demasiados comentários. O Power Apps remove todos os comentários quando cria o pacote de aplicação do cliente, para que os comentários não afetem o tamanho do pacote nem os tempos de carregamento ou de transferência da aplicação.

Estruturador de aplicações moderno com comentários

No Power Apps, é melhor usar caraterísticas de comentários no Power Apps Studio e no Estruturador de aplicações moderno.

Para adicionar comentários no Power Apps Studio, use estes 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.

Quando mencionar um colega num comentário, use o símbolo "@" seguido pelo nome. Isto envia um e-mail de notificação para a pessoa que sinalizar. Se o utilizador sinalizado não tiver acesso à aplicação, o Power Apps pede-lhe que partilhe a aplicação com ele.

Avanço e formatação

No Power Apps, o avanço e a formatação ajudam a manter a sua aplicação clara e organizada. Seguir as melhores práticas torna as suas fórmulas e controlos mais fáceis de ler.

Barra de fórmulas

Recuo

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

Quebras de linha

Divida fórmulas longas em várias linhas para facilitar a leitura. Pressione Enter para adicionar uma quebra de linha na barra de fórmulas.

Utilizar o comando Formatar texto

O comando "Formatar Texto" na barra de fórmulas adiciona avanço, espaçamento e quebras de linha ao seu código do Power Apps. Use o comando "Formatar Texto" para manter um estilo de codificação consistente na sua aplicação de tela e ajudar a evitar erros.

Próximo passo