Legibilidade do código

A legibilidade do código é um aspeto importante do desenvolvimento de aplicações que muitas vezes é negligenciado. 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 seu código. Ajuda-te a identificar rapidamente o propósito de cada elemento na tua aplicação e facilita a navegação pela tua base de código.

Convenções de nomenclatura gerais

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

Caixa de camelo

Utilize camel case para controlos 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

Use o caso Pascal para fontes de dados. O caso Pascal é, por vezes, referido como "caso camel superior". Tal como o camel case, remove todos os espaços e capitaliza a primeira letra das palavras. No entanto, ao contrário de camel case, Pascal case também capitaliza a primeira palavra. Por exemplo, uma fonte de dados comum no Power Apps é o conector Microsoft Office 365 Users, que no código se chama Office365Users.

Nomes de ecrã

Escolha nomes de utilizador que mostrem claramente o propósito do ecrã, o que facilita a navegação por aplicações complexas no Power Apps Studio.

Os leitores de ecrã leem nomes de ecrã em voz alta. Os utilizadores com necessidades de acessibilidade visual dependem destes leitores de ecrã. Use linguagem simples para nomes de utilizador, inclua espaços e evite abreviaturas. Termine cada nome com a palavra "Screen" para fornecer um contexto claro quando o nome for 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

Use o caso camelo para todos os nomes de controlo na tela. Comece com um descritor de três caracteres, seguido do propósito 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 fonte de dados à sua aplicação, não pode alterar o nome na aplicação Power Apps. O nome é herdado do conector de origem ou das entidades de dados que são derivadas da conexão.

Seguem-se alguns exemplos:

• Nome herdado do conector de origem: O conector Office 365 Users chama-se Office365Users no seu código.
• Entidades de dados derivadas da ligação: Uma lista Microsoft SharePoint chamada Employees é devolvida do conector SharePoint. Portanto, o nome da fonte de dados no seu código é Employees. A mesma aplicação Power Apps também pode usar o mesmo conector SharePoint para aceder a uma lista SharePoint chamada Contractors. Neste caso, o nome da origem de dados no código é Contractors.

Saiba mais sobre conectores e ligações na Visão Geral dos conectores para aplicações canvas.

Conectores de ação padrão

Em conectores de ação padrão que expõem funções, como o LinkedIn, o nome da fonte de dados e as suas operações utilizam carcaça Pascal. Por exemplo, a fonte de dados LinkedIn chama-se LinkedIn e tem uma operação chamada ListCompanies.

ClearCollect(
    colCompanies,
    LinkedIn.ListCompanies()
)

Conectores personalizados

Use conectores personalizados para se ligar a interfaces de programação de aplicações (APIs) personalizadas, como serviços ou APIs de linha de negócio que a sua empresa cria. Qualquer criador no teu ambiente pode criar conectores personalizados. Use o caso Pascal para o nome da fonte de dados e as suas operações. O nome do conector personalizado e a forma como aparece no Power Apps podem ser diferentes.

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

Quando cria uma ligação a partir deste conector e a adiciona à sua aplicação Power Apps como fonte de dados, aparece como AuctionItemBidAPI.

Para descobrir a razão, procure dentro do ficheiro OpenAPI um atributo 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 usa-o como nome da sua fonte de dados.

Tabelas de Dados do Excel

O Power Apps utiliza DataTables no Microsoft Excel para ligar a dados em folhas de cálculo Excel. Tenha em mente estes pontos quando criar documentos do Excel como origens de dados:

• Dê aos seus DataTables nomes descritivos. O nome aparece na aplicação Power Apps quando escreves o código para te ligares 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 das variáveis nas aplicações Canvas são importantes para manter a legibilidade, consistência e claridade nos seus projetos 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 cadeia de texto
  • 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, usar userCount consistentemente 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 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 variáveis de contexto e variáveis globais partilhem os mesmos nomes. Esta partilha pode causar confusão porque as suas fórmulas usam variáveis de contexto por defeito, a menos que use 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 ou propósito da variável. Pode usar várias palavras sem precisar de as separar por caracteres especiais, como sublinhas, se capitalizar a primeira letra de cada palavra.
• Usa carcaça de camelo. 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. Utilize EmployeeId em substituição.

Quando uma aplicação tem muitas variáveis, escreva o prefixo na barra de fórmulas para ver uma lista de variáveis disponíveis. Se seguir estas orientações para nomear as suas variáveis, pode encontrá-las facilmente na barra de fórmulas enquanto desenvolve a sua aplicação. Em última análise, esta abordagem conduz a um desenvolvimento de aplicações mais rápido e eficiente.

Nomes de coleções

• Use nomes que descrevam o conteúdo da coleção. Pensa no que a coleção contém e como é usada, e nomeia-a em conformidade.
• Prefixar os nomes das coleções com col.
• Use o nome após o prefixo para mostrar a intenção ou propósito da coleção. Pode usar várias palavras sem espaços ou sublinhados se capitalizar a primeira letra de cada palavra.
• Usa carcaça de camelo. Comece os nomes da sua coleção com um prefixo minúsculo col e depois 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

Comentários e documentação

Quando escrever código para a sua aplicação, foque-se em adicionar comentários claros. Os comentários ajudam-te a perceber o código mais tarde e tornam mais fácil para o próximo programador trabalhar no project.

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 frente (//) para notas de linha única, e comentários em bloco, que usam /* e */ para notas de várias linhas.

Comentários de linha

Adicione uma barra dupla para a frente (//) a qualquer linha de código em Power Apps para que o resto da linha seja 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 em 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. Esta abordagem ajuda quando os 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"
    }
)

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 é comentado.
3. Os comentários de linha e em bloco presentes noutras partes da propriedade são adicionados à linha de código imediatamente anterior.

Não se preocupe em adicionar comentários demasiado longos ou em excesso. O Power Apps remove todos os comentários quando cria o pacote de aplicação cliente. Os comentários não afetam o tamanho do pacote, a velocidade de download da aplicação ou os tempos de carregamento.

Designer de aplicações moderno com comentários

No Power Apps, utilize as funcionalidades de comentários tanto no Power Apps Studio como no designer moderno de aplicações.

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

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

Quando mencionar um colega num comentário, use o símbolo "@" seguido pelo nome. Esta ação envia um email de notificação à pessoa que identifica. Se o utilizador marcado não tiver acesso à aplicação, o Power Apps pede-te para partilhares a aplicação com ele.

Indentação e formatação

A indentação e a formatação ajudam a manter a sua aplicação limpa e organizada. Quando o teu código está bem formatado, é mais fácil de ler e compreender.

Recuo

Power Apps não impõe uma indentação estrita. Usa espaços para separar diferentes secções das tuas fórmulas. Pressione a barra de espaço várias vezes para criar uma reentrância.

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 Format text na barra de fórmulas adiciona indentação, espaçamento e quebras de linha ao teu código Power Apps. Use o comando Formatar texto para manter um estilo de programação consistente na sua aplicação canvas e ajudar a evitar erros.

Informações adicionais

• Usa convenções de nomenclatura consistentes nos fluxos de nuvem do Power Automate
• Construir scripts legíveis e manuteníveis nos fluxos de ambiente de trabalho do Power Automate

Próximo passo