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
Imagem img
Botão Inf Informações do
Label lbl
Vínculo lnk
Caixa de listagem lst
Microfone Microfone
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
Vídeo 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.

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. Quanto às variáveis, se você seguir estas diretrizes para nomear suas coleções, poderá encontrá-las facilmente na barra de fórmulas à medida que desenvolve seu aplicativo. Em última análise, essa abordagem leva ao desenvolvimento mais rápido de aplicativos.

Comentários e documentação

Quando você escreve código para seu aplicativo, concentre-se em adicionar comentários claros. Os comentários ajudam você a entender seu código mais tarde e facilitam o trabalho do próximo desenvolvedor no projeto.

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

Comentários de linha

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

Use comentários de linha para explicar o que a próxima linha de código faz. Você também pode usá-los para desabilitar temporariamente uma linha de código para teste.

Aqui está 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 do bloco

Texto entre /* e */ é um comentário de bloco. Os comentários de bloco podem abranger várias linhas, ao contrário dos comentários de linha, que cobrem apenas uma linha.

Use comentários de bloco para explicações mais longas, como documentar um cabeçalho de módulo de código. Você também pode usá-los para desabilitar 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 o recurso Formatar Texto. Isso ajuda se 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"
    }
)

O recurso Formatar Texto segue estas regras para comentários:

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

Não se preocupe em adicionar muitos comentários ou muito longos. O Power Apps remove todos os comentários quando cria o pacote do aplicativo cliente, para que os comentários não afetem o tamanho do pacote nem diminuam as transferências ou os tempos de carregamento do aplicativo.

Designer de aplicativo moderno com comentários

No Power Apps, é melhor usar os recursos de comentários em ambos designer de aplicativo Moderno e do Power Apps Studio.

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

Quando você mencionar um colega em um comentário, use o símbolo "@" seguido do nome dele. Isso envia um email de notificação para a pessoa que você marca. Se o usuário marcado não tiver acesso ao aplicativo, o Power Apps solicitará que você compartilhe o aplicativo com ele.

Captura de tela de um aplicativo de despesas mostrando uma pessoa mencionada com @ em um comentário.

Recuo e formatação

No Power Apps, o recuo e a formatação ajudam a manter seu aplicativo claro e organizado. Seguir as práticas recomendadas torna suas fórmulas e controles mais fáceis de ler.

Barra de fórmulas

Recuo

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

Quebras de linha

Divida fórmulas longas em várias linhas para torná-las mais fáceis de ler. Pressione Enter para adicionar uma quebra de linha na barra de fórmulas.

Usar o comando Formatar texto

O comando "Formatar Texto" na barra de fórmulas adiciona recuo, 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 em seu aplicativo de tela e ajudar a evitar erros.

Captura de tela do Power Apps Studio com o comando Formatar Texto destacado.

Próxima etapa

Otimização de código

  • Last updated on