Trabalhar com instruções de comentário e compostas
Quando você está escrevendo código para qualquer linguagem de programação, é uma boa prática comentar seu código. Um comentário é uma descrição ou uma explicação adicional no código sobre ele. As instruções de comentário não são consideradas codificação. As instruções estão disponíveis apenas para que outros desenvolvedores possam compreender melhor o código que você escreveu.
Você pode comentar usando duas barras (//), da seguinte maneira:
// This is a comment
No Visual Studio Code, você pode selecionar Editar e Alternar o Comentário da Linha (ou usar as teclas de atalho Ctrl+:) para comentar.
Para comentar um bloco de código inteiro, você pode usar /*e*/.
No Visual Studio Code, você pode selecionar Editar e Alternar o Comentário do Bloco (ou usar as teclas de atalho Alt + Shift + A) para comentar em um bloco de códigos.
/* This is a comment
on multiple
multiple
multiple
lines. */
Comentários XML no código
No Dynamics 365 Business Central, você pode adicionar uma documentação ao código, incluindo elementos XML em campos de comentários especiais diretamente no código-fonte antes do bloco de códigos a que o comentário se refere.
O comentário da documentação deve preceder imediatamente um tipo definido pelo usuário que ele anota, por exemplo, uma codeunit, uma tabela ou uma interface, ou um membro, como campo ou método.
A sintaxe para adicionar comentários XML ao seu código é de barras triplas /// seguidas por uma das marcas XML com suporte.
O IntelliSense dá suporte para escrever comentários de documentação. O mais importante é inserir um comentário de documentação de modelo ao escrever a terceira barra da barra tripla.
Os comentários de documentação são exibidos ao mover o cursor do mouse sobre os símbolos de origem, nas listas de conclusão e na ajuda da assinatura.
Adicionando comentários XML no código, você pode melhorar a legibilidade, adicionar informações úteis sobre a implementação e ajudar outras pessoas a controlar o código que você escreveu. Com comentários XML, você habilita o IntelliSense no Visual Studio Code nos objetos AL que decide adicionar ao código, como uma ajuda para outros desenvolvedores que trabalham com seu código ou o estendem. Isso significa que, quando você criar uma extensão e alguém estender esse código, essa pessoa obterá a documentação embutida quando chamar o objeto em questão.
Veja mais informações sobre as Marcas XML compatíveis.
O exemplo a seguir foi extraído do arquivo Email.Codeunit.al no aplicativo do sistema. Neste exemplo, o parâmetro EmailMessageId foi documentado usando a sintaxe <param>.
/// <summary>
/// Provides functionality to create and send e-mails.
/// </summary>
codeunit 8901 "Email"
{
Access = Public;
/// <summary>
/// Enqueues an email in the outbox to be sent in the background.
/// </summary>
/// <param name="EmailMessageId">The ID of the email to enqueue</param>
procedure Enqueue(EmailMessageId: Guid)
begin
EmailImpl.Enqueue(EmailMessageId);
end;
...
Para que símbolos especiais, como colchetes angulares, apareçam no texto de um comentário de documentação, use a codificação HTML de < e >, que é < e > respectivamente.
O exemplo a seguir ilustra esse procedimento.
/// <summary>
/// This property always returns a value < 1.
/// </summary>
Os comentários de código melhoram a legibilidade do código que você desenvolveu e são muito úteis para qualquer pessoa que modifique ou mantenha esse código. Além disso, os comentários de código formam a base da documentação gerada automaticamente.
Ótimos comentários de código fazem o seguinte:
Nunca dizem o óbvio.
Escreva um comentário significativo; use as palavras precisas para descrever o porquê.
Imagine-se no lugar do desenvolvedor usando esse trecho de código; o que você gostaria de saber?
Para propriedades e métodos, use palavras ativas como Define..., Obtém... e Especifica... e, em seguida, explique o que elas fazem.
Liste todas as pré-condições para seus parâmetros (não pode ser nulo, deve estar em determinado intervalo e assim por diante) '.
Liste quaisquer pós-condições que possam influenciar como os chamadores lidam com os valores de retorno.
Liste as exceções que o método pode lançar (e em que circunstâncias).
Se houver métodos semelhantes, explique as diferenças entre eles.
Chame atenção para algo inesperado (como modificar o estado global).
Enumere os efeitos colaterais, se houver algum.
Seja consistente e conciso.
Verifique se os comentários foram revisados.
Diretiva do compilador de região de código
Use regiões de código para estruturar o código relacionado, adicionar documentação de seções de código e expandir ou recolhê-los para a rápida navegação no seu código com fácil delineamento do código.
As diretivas são uma nova construção em linguagem AL que especifica como o compilador AL processa uma seção delimitada de código. O mesmo conceito é conhecido em outras linguagens. As instruções específicas da diretiva devem ter apoio do compilador — não é possível criar instruções personalizadas de pré-processamento.
A diretiva #region é usada para marcar um bloco de códigos que pode ser expandido ou recolhido. Isso pode ser útil, por exemplo, em arquivos maiores, para melhorar a legibilidade ou para enfocar o código no qual você está trabalhando. A diretiva #endregion especifica o fim de um bloco de códigos #region.
Um bloco #region deve terminar com uma diretiva #endregion. Um bloco #region não pode se sobrepor a um bloco #if. No entanto, um bloco #region pode estar aninhado em um bloco #if, e um bloco #if pode estar aninhado em um bloco #region.
Neste exemplo, a diretiva #region torna recolhível um bloco de códigos que está pronto para refatoração:
#region Ugly code - let's not look at this
procedure UglyCode()
begin
// No one should look at this
end;
#endregion
Exemplo de definição de regiões em uma unidade de código:
Exemplo de como recolher regiões:
Instruções compostas
Uma instrução composta consiste em várias instruções. As instruções compostas são indicadas por começo e fim e tudo em cada um deles é um demonstrativo composto.
begin
statement 1;
statement 2;
statement 3;
...
end