Compartilhar via

Legibilidade do código

A legibilidade de código é um aspecto importante do desenvolvimento de aplicativos que muitas vezes é ignorado. O código legível é mais fácil de entender, manter e depurar.

Convenções de nomenclatura

Convenções de nomenclatura consistentes melhoram significativamente a legibilidade do código. Ele ajuda a identificar rapidamente a finalidade de cada elemento em seu aplicativo e facilita a navegação pela base de código.

Convenções gerais de nomenclatura

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

Notação camel case

Use camel case (letras maiúsculas e minúsculas intercaladas) para controles e variáveis. A notação camel case 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.

Pascal Case

Utilize PascalCase para fontes de dados. Pascal Case é por vezes referido como "camel case superior". 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 do CamelCase, o PascalCase também coloca a primeira palavra em maiúscula. Por exemplo, uma fonte de dados comum no Power Apps é o conector Microsoft Office 365 Users, que é denominado Office365Users no código.

Nome de exibição

Escolha nomes de tela que mostram claramente a finalidade da tela, o que facilita a navegação por aplicativos complexos no Power Apps Studio.

Os leitores de tela leem nomes de tela em voz alta. Os usuários com necessidades de acessibilidade visual dependem desses leitores de tela. Use o idioma sem formatação para nomes de tela, inclua espaços e evite abreviações. Termine cada nome com a palavra "Tela" para garantir um contexto claro 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

Use camel case para todos os nomes de controle na tela. Comece com um descritor de tipo de três caracteres, seguido pela 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
Distintivo bdg
Botão btn
Controle de câmera câmera
Tela poder
Cartão crd
Gráficos chr
CheckBox chk
Coleção coluna
Caixa de combinação cmb
Componente cmp
Contêiner con
Datas dte
Lista suspensa drp
Formulário frm
Galeria galão
Grupo grupo
Cabeçalho hdr
Texto HTML htm
Ícone ico
Imagem img
Botão de Informação Informações
Etiqueta lbl
Vínculo lnk
Caixa de listagem lst
Microfone Microfone
Microsoft Stream str
Forma da seção de página seg
Entrada de Caneta pen
Bloco Power BI pbi
Barra de Progresso pbar
Avaliação rtg
Editor de texto rico rte
Formas (retângulo, círculo etc.) shp
Controle deslizante sld
Lista de Abas aba
Tabela tbl
Entrada de texto txt
Temporizador amanhã
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 curto da tela 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 do modo de exibição de navegação mostrando nomes de controle seguindo o padrão descrito.

Nomes da fonte de dados

Quando você adiciona uma fonte de dados ao seu aplicativo, não é possível alterar o nome no aplicativo 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 Office 365 Users é chamado Office365Users em seu código.
  • As entidades de dados derivadas da conexão: Uma lista do Microsoft SharePoint chamada Employees é retornada do conector SharePoint. Portanto, o nome da fonte de dados em seu código é Employees. O mesmo aplicativo do 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.

Saiba mais sobre conectores e conexões em Visão geral dos conectores para aplicativos de tela.

Conectores de ação padrão

Em conectores de ação padrão, como os que expõem funções do LinkedIn, o nome da fonte de dados e suas operações usam Pascal Case. Por exemplo, a fonte de dados LinkedIn é nomeada LinkedIn e tem uma operação chamada ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Conectores personalizados

Use conectores personalizados para se conectar a APIs (interfaces de programação de aplicativos) personalizadas, como serviços ou APIs de linha de negócios criadas pela sua empresa. Qualquer criador em seu ambiente pode criar conectores personalizados. Use o casing pascal para o nome da fonte de dados e suas operações. O nome do conector personalizado e a forma como ele aparece em Power Apps podem ser diferentes.

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

Captura de tela de um conector chamado MS API de Lance de Item de Leilão.

Quando você cria uma conexão com esse conector e a adiciona ao aplicativo Power Apps como uma fonte de dados, ela aparece como AuctionItemBidAPI.

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

Para descobrir o motivo, procure dentro do arquivo OpenAPI um atributo de título que contenha o texto Auction Item Bid API.

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

Power Apps remove todos os espaços desse valor de atributo e o usa como o nome da fonte de dados.

Dica

Altere o valor desse atributo para um nome no estilo Pascal, como AuctionItemBidAPI, e use-o como nome da sua conexão personalizada. Dessa forma, não há 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 a partir de um em branco em vez de importar um arquivo OpenAPI existente, o Power Apps solicitará o nome do conector personalizado. Esse nome é o nome do conector personalizado e o valor do atributo de título dentro do arquivo OpenAPI. Use um nome em PascalCase, como AuctionItemBidAPI, para manter as coisas consistentes e simples.

Tabelas de Dados do Excel

O Power Apps usa DataTables em 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 o padrão de capitalização de Pascal. Cada palavra do nome da Tabela de Dados deve começar com uma letra maiúscula, como EmployeeLeaveRequests.

Nomes da variável

Convenções de nomenclatura para variáveis em apps de canvas são importantes para manter a legibilidade, consistência e 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 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 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 userCount ou users.
  • Evite usar palavras ou nomes reservados que possam entrar em conflito com Power Apps funções ou palavras-chave. Verifique 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.

Power Apps permite que variáveis de contexto e variáveis globais compartilhem os mesmos nomes. Esse compartilhamento pode causar confusão porque suas fórmulas usam variáveis de contexto por padrão, a menos que você use o operador de desambiguação.

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 ou a finalidade da variável. Você pode usar várias palavras sem precisar separá-las por caracteres especiais, como sublinhados, se você capitalizar a primeira letra de cada palavra.
  • Use maiúsculas de camelo. 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. Use EmployeeId em seu lugar.

Quando um aplicativo tiver muitas variáveis, digite o prefixo na barra de fórmulas para ver uma lista de variáveis disponíveis. Se você seguir essas diretrizes para nomear suas variáveis, poderá encontrá-las facilmente na barra de fórmulas à medida que desenvolve seu aplicativo. Em última análise, essa abordagem leva a um desenvolvimento de aplicativo mais rápido e eficiente.

Nomes de coleções

  • Use nomes que descrevem o conteúdo da coleção. Pense no que a coleção contém e como ela é usada e nomeie-a adequadamente.
  • Prefixe os nomes das coleções com col.
  • Use o nome após o prefixo para mostrar a intenção ou a finalidade da coleção. Você pode usar várias palavras sem espaços ou sublinhados se capitalizar a primeira letra de cada palavra.
  • Use maiúsculas de camelo. Inicie seus nomes de coleção com um prefixo minúsculo col e, em seguida, capitalize 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 um aplicativo tiver muitas coleções, digite o prefixo na barra de fórmulas para ver uma lista de coleções disponí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. Essa abordagem leva a um desenvolvimento de aplicativo mais rápido.

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 o código mais tarde e facilitam o trabalho do próximo desenvolvedor no project.

Power Apps dá suporte a dois estilos de comentário para deixar seu código mais claro: comentários de linha, que usam barras duplas (//) para anotações de linha única e comentários de bloco, que usam /* e */ para anotações de várias linhas.

Comentários de linha

Adicione uma barra dupla (//) a qualquer linha de código em 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 em 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. Essa abordagem ajuda quando seus comentários aparecem 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 linha de código seguinte não será adicionada a ela. Caso contrário, o código é comentado.
  3. Comentários de linha e bloco em outros locais da propriedade são adicionados à linha de código anterior.

Não se preocupe em adicionar comentários que sejam muitos ou muito longos. Power Apps remove todos os comentários ao criar o pacote do aplicativo cliente. Os comentários não afetam o tamanho do pacote, a velocidade de download do aplicativo ou os tempos de carregamento.

Designer de aplicativo moderno com comentários

Em Power Apps, use os recursos de comentário no Power Apps Studio e no designer de aplicativos moderno.

Para adicionar comentários no Power Apps Studio, use estes métodos:

  • Clique com o botão direito do mouse nas reticências ("...") de qualquer item no Modo de Exibição de Árvore.
  • Clique com o botão direito do mouse em um componente na área de tela.
  • 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. Essa ação envia um email de notificação para a pessoa que você marca. Se o usuário marcado não tiver access 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

O recuo e a formatação ajudam a manter seu aplicativo claro e organizado. Quando o código está bem formatado, é mais fácil ler e entender.

Recuo

Power Apps não impõe recuo estrito. Use espaços para separar seções diferentes de suas fórmulas. Pressione a barra de espaços 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 Format text na barra de fórmulas adiciona recuo, espaçamento e quebras de linha ao código Power Apps. Use o comando Formatar texto para manter um estilo de codificação consistente em seu aplicativo de tela e para ajudar a evitar erros.

Screenshot do Power Apps Studio com o comando formatar texto realçado.

Próxima etapa

Otimização de código

  • Last updated on