Compartilhar via

Legibilidade do código

Convenções de nomenclatura

Convenções gerais de nomenclatura

Esta seção descreve as convenções de nomenclatura "Uso de minúsculas concatenadas" e "Uso de maiúsculas e minúsculas em Pascal". Se você já estiver familiarizado com esses termos, pode ignorar.

Usar minúsculas concatenadas

Você deve usar minúsculas concatenadas para controles e variáveis. A minúscula concatenada começa com um prefixo minúsculo, remove todos os espaços de nomes de objetos ou variáveis e coloca a primeira letra de cada palavra em maiúscula após a primeira. Por exemplo, um controle de entrada de texto pode ser chamado txtUserEmailAddress.

Uso de maiúsculas e minúsculas em Pascal

Você deve usar maiúsculas e minúsculas em Pascal para fontes de dados. O uso de maiúsculas e minúsculas em Pascal é por vezes referido como "camel case com inicial maiúscula". Como o camel case, ele remove todos os espaços e coloca em maiúscula a primeira letra das palavras. No entanto, ao contrário de minúsculas concatenadas, o Uso de maiúsculas e minúsculas em Pascal também coloca a primeira palavra em maiúscula. Por exemplo, uma fonte de dados comum no PowerApps é o conector de Usuários do Microsoft Office 365, denominado Office365Users em seu código.

Nomes de tela

Os nomes de telas devem refletir a finalidade da tela, para que seja mais fácil navegar por aplicativos complexos no Power Apps Studio.

O que é menos óbvio é que os nomes de tela são lidos em voz alta pelos leitores de tela, o que é necessário para usuários que têm necessidades de acessibilidade visual. Portanto, é necessário que você use linguagem simples para nomear suas telas e que os nomes tenham espaços e não tenham abreviações. Além disso, recomendamos que você termine o nome com a palavra "Tela", para que o contexto seja compreendido quando o nome for anunciado.

Veja alguns bons exemplos:

  • Home_Screen ou Home Screen
  • Search_Screen ou Search Screen

Captura de tela que mostra uma lista de nomes de tela que seguem o padrão descrito

Estes exemplos de nomes de tela são menos compreensíveis:

  • Home
  • LoaderScreen
  • EmpProfDetails
  • Thrive Help

Nomes de controles

Todos os nomes de controle na tela devem usar minúsculas concatenadas. Eles devem começar com um descritor do tipo de três caracteres, seguido da finalidade do controle. Essa abordagem ajuda a identificar o tipo de controle e facilita a criação de fórmulas e pesquisas. Por exemplo, lblUserName indica que o controle é um rótulo.

A tabela a seguir mostra as abreviações de controles comuns.

Nome do controle Abreviação
Notificação bdg
Button btn
Controle de câmera cam
Tela can
Card crd
Gráficos chr
CheckBox chk
Coleção col
Caixa de combinação cmb
Componente cmp
Contêiner con
Datas dte
Lista suspensa drp
Formulário frm
Galeria gal
Agrupar grp
Cabeçalho hdr
Texto/html htm
Icon ico
Image img
Botão Inf Informações do
Label lbl
Vínculo lnk
Caixa de listagem lst
Microfone mic
Microsoft Stream str
Forma da seção de página s
Entrada à Caneta pen
Bloco do Power BI pbi
Barra de Progresso pbar
Avaliação rtg
Editor de rich text rte
Formas (retângulo, círculo etc.) shp
Controle deslizante sld
Lista de Guias tbl
Table tbl
Entrada de texto txt
Temporizador tmr
Alternar tgl
Video vid

Lista detalhada de controles e suas propriedades são descritas em Referência de controles.

Observação

Os nomes de controle devem ser exclusivos em um aplicativo. Se um controle for reutilizado em várias telas, o nome da tela curta deverá ter um sufixo. Por exemplo, galBottomNavMenuHS, onde "HS" significa "Home Screen" (Tela Inicial). Essa abordagem facilita a referência ao controle em fórmulas nas telas.

Veja alguns exemplos ruins:

  • zipcode
  • Next

Quando você nomeia consistentemente seus controles, seu aplicativo fica mais limpo na exibição de navegação e seu código também fica mais limpo.

Captura de tela da exibição de navegação mostrando os nomes de controle seguindo o padrão

Nomes da fonte de dados

Quando você adiciona um fonte de dados ao seu aplicativo, o nome não pode ser alterado no aplicativo do Power Apps. O nome é herdado do conector de origem ou de entidades de dados derivadas da conexão.

Veja alguns exemplos:

  • Nome herdado do conector de origem: O conector de Usuários do Office 365 é namedOffice365Users em seu código.
  • Entidades de dados derivadas da conexão: Uma lista da Microsoft SharePoint nomeada Employees é retornada do conector do SharePoint. Portanto, o nome da fonte de dados em seu código é Employees. O mesmo aplicativo Power Apps também pode usar o mesmo conector do SharePoint para acessar uma lista do SharePoint chamada Contractors. Nesse caso, o nome da fonte de dados no código é Contractors.

Para obter mais informações sobre conectores e conexões, consulte Visão geral de conectores de aplicativo de tela para o Power Apps.

Conectores de ação padrão

Nos conectores de ação Padrão que expõem funções, como LinkedIn, o nome da fonte de dados e suas operações usam maiúsculas e minúsculas em Pascal. Por exemplo, a fonte de dados do LinkedIn é chamada LinkedIn e tem uma operação chamada ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Conectores personalizados

Conectores personalizados usados para se conectar a APIs (interfaces de programação de aplicativos) personalizadas como serviços ou APIs de linha de negócios que sua empresa criou. Eles podem ser criados por qualquer criador no seu ambiente. Recomendamos o uso de maiúsculas e minúsculas em Pascal para o nome da fonte de dados e suas operações. Apenas esteja ciente de que o nome do conector personalizado e a maneira como ele aparece no PowerApps podem ser diferentes.

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

Captura de tela de um conector chamado API de Lance do Item de Leilão (Auction Item Bid API) da MS

Mas quando você cria uma conexão a partir desse conector e a adiciona ao seu aplicativo PowerApps como uma fonte de dados, ela aparece como AuctionItemBidAPI.

Captura de tela de um conector mostrando que o nome é AuctionItemBidAPI

Para descobrir o motivo, você pode procurar no arquivo do OpenAPI um atributo de título 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 o usa como o nome da sua fonte de dados.

Dica

Recomendamos que você altere o valor desse atributo para um nome com maiúsculas e minúsculas em Pascal, como AuctionItemBidAPI e use-o como o nome de sua conexão personalizada. Dessa forma, não haverá confusão. Altere esse valor antes de importar o arquivo OpenAPI para criar o conector personalizado.

Observação

Se você usar a opção Criar de um modelo em branco, em vez de importar um arquivo OpenAPI existente, o PowerApps solicitará o nome do conector personalizado. Esse nome será usado como o nome do conector personalizado e como o valor do atributo de título dentro do arquivo OpenAPI. Certifique-se de usar um nome com maiúsculas e minúsculas em Pascal como AuctionItemBidAPI para manter as coisas consistentes e simples.

Tabelas de Dados do Excel

O PowerApps usa Tabelas de Dados no Microsoft Excel para se conectar a dados em planilhas do Excel. Lembre-se destes pontos ao criar documentos do Excel como fontes de dados:

  • Dê nomes descritivos às suas Tabelas de Dados. O nome está no aplicativo Power Apps quando você escreve o código para se conectar a ele.
  • Use uma Tabela de Dados por planilha.
  • Dê o mesmo nome à Tabela de Dados e à planilha.
  • Use nomes de coluna descritivos em Tabelas de Dados.
  • Use maiúsculas e minúsculas em Pascal. Cada palavra do nome da Tabela de Dados deve começar com uma letra maiúscula, como EmployeeLeaveRequests.

Objetos sem tipo e dinâmicos

Nomes da variável

As convenções de nomenclatura para variáveis em aplicativos de tela são importantes para manter a legibilidade, a consistência e a clareza em seus projetos do Power Apps. Embora nenhum padrão estrito seja imposto, adotar uma convenção de nomenclatura consistente em seu aplicativo de tela pode facilitar a compreensão, o uso e o gerenciamento das variáveis para você e outros colaboradores.

  • Use maiúsculas e minúsculas concatenadas, 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 excessivamente genéricos, como temp ou var1. Em vez disso, use nomes descritivos como userEmail ou totalAmount.
  • Considere o uso de prefixos ou sufixos para indicar o tipo de variável. Por exemplo:
    • strUserName para um texto/cadeia de caracteres/variável
    • numTotalAmount para uma variável numérica
    • boolIsEnabled para uma variável booliana
    • locVarName para variáveis locais/variáveis de contexto
    • gblVarLoginUser para variáveis globais
  • Decida se suas variáveis devem ser nomeadas no singular ou plural e mantenha essa convenção. Por exemplo, use consistentemente userCount ou users.
  • Evite usar palavras ou nomes reservados que possam entrar em conflito com funções ou palavras-chave do Power Apps. Consulte a documentação do Power Apps para obter uma lista de palavras reservadas.
  • Considere o uso de prefixos que forneçam contexto sobre o uso ou escopo da variável. Por exemplo:
    • frm para variáveis de formulários
    • col para coleções
    • var para variáveis de uso geral
  • Evite caracteres especiais. Mantenha os nomes alfanuméricos e evite caracteres especiais ou espaços. Use letras e números.

O Power Apps permite que variáveis de contexto e variáveis globais compartilhem os mesmos nomes. Isso pode causar confusão porque suas fórmulas usam variáveis de contexto por padrão, a menos que o operador de desambiguação seja usado.

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

  • Prefixe variáveis de contexto com loc.
  • Prefixe 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.
  • Usar maiúsculas e minúsculas concatenadas. Comece seus nomes de variáveis com um prefixo em letras minúsculas e, em seguida, coloque em maiúsculas a primeira letra de cada palavra no nome.

Esses exemplos seguem padrões e convenções:

  • Variável global:gblFocusedBorderColor

  • Variável de contexto:locSuccessMessage

  • Variável de escoposcpRadius

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. Em vez disso, Use EmployeeId.

Quando há muitas variáveis em um aplicativo, basta digitar o prefixo na barra de fórmulas para ver uma lista das variáveis disponíveis. Se você seguir essas diretrizes para nomear suas variáveis, poderá encontrá-las facilmente na barra de fórmulas ao desenvolver seu aplicativo. Em última análise, essa abordagem leva ao desenvolvimento mais rápido de aplicativos.

Nomes de coleções

  • Seja descritivo no conteúdo da coleção. Pense no que a coleção contém e/ou como ela é usada e nomeie-a adequadamente.
  • As coleções devem ser prefixadas com col.
  • O nome após o prefixo deve indicar a intenção ou finalidade da coleção. Várias palavras podem ser usadas e não precisam ser separadas por espaços ou sublinhados, se a primeira letra de cada palavra estiver em maiúsculas.
  • Usar maiúsculas e minúsculas concatenadas. Comece seus nomes de coleção com um prefixo de coluna em letras minúsculas e, em seguida, coloque em maiúsculas 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

Dica

Quando há muitas coleções em um aplicativo, basta digitar o prefixo na barra de fórmulas para ver uma lista das coleções disponíveis. Como para variáveis, se você seguir essas diretrizes para nomear suas coleções, poderá encontrá-las muito facilmente na barra de fórmulas ao desenvolver seu aplicativo. Em última análise, essa abordagem leva ao desenvolvimento mais rápido de aplicativos.

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 apenas 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.

Há 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, denotados por barras duplas (//) para observações de linha única, e comentários em bloco entre /* e */ para anotações de 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. Eles também podem servir para desabilitar temporariamente uma linha de código, tornando-os benéficos para fins de teste.

Este exemplo mostra o uso 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 do bloco

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

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

Para uma organização ideal do código, é aconselhável adicionar comentários depois de utilizar o recurso Formatar texto. Isso é vantajoso, se seus comentários precedem 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"
    }
)

O recurso Formatar texto segue estas regras para comentários existentes:

  1. Se uma propriedade começar com um comentário de 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á acrescentada a ela. Caso contrário, o código é comentado.
  3. Comentários de linha e bloco em outro lugar da propriedade serão acrescentados à linha anterior de código.

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 do aplicativo do cliente. Portanto, eles não afetarão o tamanho do pacote ou retardarão o tempo de download ou carregamento do aplicativo.

Designer de aplicativo moderno com comentários

No Power Apps, é considerada a melhor prática para os criadores utilizarem com eficácia os recursos de comentários dentro do designer de aplicativo Moderno e do Power Apps Studio.

Para um envolvimento ideal no Power Apps Studio, os criadores são aconselhados a adicionar comentários usando os seguintes métodos:

  1. Clique com o botão direito do mouse nas reticências ("...") de qualquer item no Modo de Exibição de Árvore.
  2. Clique com o botão direito do mouse em um componente na área de tela.
  3. Selecione o botão “Comentários” localizado na barra de comandos no canto superior direito da tela.

Ao mencionar colegas nos comentários, é recomendável usar o símbolo "@" seguido do nome deles. Isso solicita um email de notificação para o colega marcado, garantindo acesso rápido ao comentário. Nos casos em que um usuário marcado não tem acesso ao aplicativo, é solicitado que o criador compartilhe o aplicativo com ele.

Uma captura de tela de um aplicativo de despesas mostrando uma pessoa @ mencionada no comentário

Recuo e formatação

No Power Apps, o recuo e a formatação são importantes para manter uma estrutura clara e organizada no aplicativo. As melhores práticas a seguir melhoram a legibilidade de suas fórmulas e controles.

Barra de fórmulas

Recuo

Embora o Power Apps não imponha recuo estrito, você pode usar espaços para separar visualmente diferentes seções de suas fórmulas. Pressione a barra de espaço várias vezes para criar um efeito de recuo.

Quebras de linha

Você pode dividir fórmulas longas em várias linhas para melhorar a legibilidade. Pressione Enter para criar uma quebra de linha na barra de fórmulas.

Usar o comando Formatar texto

O comando "Formatar texto" na barra de fórmulas foi projetado para aplicar recuo, espaçamento e quebras de linha ao código do Power Apps. Utilize o comando "Formatar texto" para estabelecer um estilo de codificação uniforme em todo o aplicativo de tela, garantindo um processo de desenvolvimento mais eficiente e resistente a erros.

Captura de tela do Power Apps Studio com o comando Formatar texto realçado

Próxima etapa

Otimização de código