Uso di istruzioni di commento e istruzioni composte

Completato

Quando si scrive codice per qualsiasi linguaggio di programmazione, è buona norma aggiungere commenti. Un commento è una descrizione o una spiegazione aggiuntiva sul codice, inserita nel codice stesso. Le istruzioni di commento non sono considerate codice. Sono disponibili solo perché altri sviluppatori possano comprendere meglio il codice scritto.

È possibile commentare usando due barre (//), come segue:

// This is a comment

In Visual Studio Code è possibile selezionare Modifica, quindi Attiva/Disattiva commento per la riga (o usare i tasti di scelta rapida CTRL+:) per commentare.

Per commentare un intero blocco di codice, è possibile usare /* e */.

In Visual Studio Code è possibile selezionare Modifica, quindi Attiva/Disattiva commento per il blocco (o usare i tasti di scelta rapida ALT+MAIUSC+A) per commentare un blocco di codice.

/* This is a comment
   on multiple
   multiple
   multiple
   lines. */

Commenti XML nel codice

In Dynamics 365 Business Central è possibile aggiungere documentazione al codice includendo elementi XML in campi speciali di commento direttamente nel codice origine prima del blocco di codice a cui fa riferimento il commento.

Il commento della documentazione deve essere immediatamente precedente a un tipo definito dall'utente (UDT) che annota, ad esempio una codeunit, una tabella o un'interfaccia, oppure a un membro, ad esempio un campo o un metodo.

La sintassi per l'aggiunta di commenti XML nel codice è la tripla barra ///, seguita da uno dei tag XML supportati.

Per la scrittura di commenti della documentazione è disponibile il supporto IntelliSense. La cosa più importante è fornire un commento della documentazione del modello quando si scrive la terza barra nella tripla barra.

I commenti della documentazione sono visibili quando si passa con il mouse sui simboli di origine, negli elenchi di completamento e nella guida per la firma.

Aggiungendo commenti XML al codice, è possibile migliorare la leggibilità, aggiungere informazioni utili sull'implementazione e aiutare gli altri utenti ad acquisire il codice scritto in precedenza. I commenti XML permettono poi di abilitare IntelliSense in Visual Studio Code sugli oggetti AL eventualmente aggiunti al codice come aiuto per altri sviluppatori, che lavorano sul codice o intendono estenderlo. Ciò significa che, se si crea un'estensione e qualcuno estende questo codice, quest'ultimo riceverà la documentazione in linea quando chiama l'oggetto specificato.

Altre informazioni sui tag XML supportati.

L'esempio seguente è tratto dal file Email.Codeunit.al dell'applicazione di sistema. In questo esempio, il parametro EmailMessageId è documentato usando la sintassi <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;
...

Per fare in modo che simboli speciali, come le parentesi uncinate, appaiano nel testo di un commento sulla documentazione, usare la codifica HTML di < e >, ossia < e > rispettivamente. L'esempio seguente illustra come fare.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

I commenti del codice migliorano la leggibilità del codice sviluppato e sono molto utili per chiunque modifichi o mantenga quel codice. Inoltre i commenti del codice costituiscono la base della documentazione generata automaticamente.

Per immettere commenti del codice di impatto, attenersi alle seguenti istruzioni:

• Non affermare mai l'ovvio.

• Scrivere un commento significativo, usando una formulazione precisa per descrivere il perché.

• Mettersi nei panni dello sviluppatore che usa questo pezzo di codice: che cosa si desidera sapere?

• Per le proprietà e i metodi usare parole attive come Imposta..., Ottiene... e Specifica..., quindi spiegare che cosa fa.

• Elencare tutte le precondizioni per i parametri (non possono essere nulli, devono rientrare in un determinato intervallo e così via).

• Elencare eventuali condizioni successive che potrebbero influenzare il modo in cui i chiamanti gestiscono i valori restituiti.

• Elencare eventuali eccezioni che il metodo può generare (e in quali circostanze).

• Se esistono metodi simili, spiegare le differenze.

• Richiamare l'attenzione su qualsiasi aspetto inaspettato (come la modifica dello stato globale).

• Elencare eventuali effetti collaterali.

• Essere coerenti e concisi.

• Assicurarsi che qualcuno riveda i commenti.

Direttiva del compilatore dell'area del codice

Usare le aree del codice per strutturare il codice correlato, aggiungere la documentazione delle sezioni di codice ed espanderle o comprimerle per una navigazione rapida nel codice con una facile struttura del codice.

Le direttive sono un nuovo costrutto nel linguaggio AL che specifica come il compilatore AL tratta una sezione di codice racchiusa. Lo stesso concetto è noto in altri linguaggi. Le istruzioni specifiche delle direttive devono essere supportate dal compilatore. Non è possibile creare istruzioni di pre-elaborazione personalizzate.

La direttiva #region si usa per contrassegnare un blocco di codice che è possibile espandere o comprimere. Questo può, ad esempio, essere utile in caso di file più grandi per una migliore leggibilità o per concentrarsi sul codice a cui si sta lavorando. La direttiva #endregion specifica la fine di un blocco di codice #region.

Un blocco #region deve terminare con una direttiva #endregion. Un blocco #region non può sovrapporsi a un blocco #if. Tuttavia, un blocco #region può essere nidificato in un blocco #if e un blocco #if può essere nidificato in un blocco #region.

In questo esempio la direttiva #region esegue un blocco di codice per un refactoring comprimibile:

#region Ugly code - let's not look at this
    procedure UglyCode()
    begin
        // No one should look at this
    end;
#endregion

Esempio di definizione di aree in una codeunit:

Esempio di aree compresse:

Istruzioni composte

Un'istruzione composta è un'istruzione costituita da più istruzioni. Le istruzioni composte sono delimitate da begin ed end; tutto ciò che vi è compreso è un'unica istruzione composta.

begin
  statement 1;
  statement 2;
  statement 3;
  ...
end