Comentarios

Puede realizar comentarios mediante dos barras diagonales (//), de la siguiente manera:

// This is a comment

Para comentar un bloque completo de código, puede usar /* y */.

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

Comentarios XML en el código

La sintaxis para agregar comentarios XML en su código es triple barra /// seguido de una de las etiquetas XML admitidas.

Al agregar comentarios XML en el código, puede mejorar la legibilidad, agregar información útil sobre la implementación y ayudar a otros a hacerse cargo del código que escribió. Con los comentarios XML también habilita IntelliSense en Visual Studio Code en los objetos de AL que agrega en su código como ayuda para otros desarrolladores, que trabajan con su código o lo amplían. Esto significa que cuando haya creado una extensión y alguien amplíe este código, obtendrá documentación en línea cuando llame al objeto determinado.

/// <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 los símbolos especiales, como los corchetes angulares, aparezcan en el texto de un comentario de documentación, use la codificación HTML de < y >, que es < y >, respectivamente. En el ejemplo siguiente se ilustra cómo hacerlo.

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

Los buenos comentarios de código hacen lo siguiente:

• Nunca diga lo obvio.
• Escriba un comentario significativo, utilice una redacción precisa para describir por qué.
• Póngase en la piel del desarrollador que utiliza este código, ¿qué le gustaría saber?
• Para las propiedades y los métodos, utilice palabras activas como Sets…, Gets… y Specifies…, y luego explique lo que hace.
• Enumere todas las condiciones previas para sus parámetros (no pueden ser nulos, deben encontrarse dentro de un rango determinado, etc.).
• Enumere las condiciones posteriores que podrían influir en cómo los autores de llamada tratan los valores devueltos.
• Enumere las excepciones que el método puede arrojar (y bajo qué circunstancias).
• Si existen métodos similares, explique las diferencias entre ellos.
• Llame la atención sobre cualquier cosa inesperada (como modificar el estado global).
• Enumere los efectos secundarios, si los hay.
• Sea uniforme y conciso.
• Asegúrese de que sus comentarios se revisen.

Regiones de código

Use regiones de código para estructurar el código relacionado, agregar documentación de secciones de código y expandirlas o contraerlas para una navegación rápida en su código con un esquema sencillo del código.

La directiva #region se usa para marcar un bloque de código que se puede expandir o contraer. Esto puede resultar útil, por ejemplo, para archivos más grandes para una mejor legibilidad o para centrarse en el código en el que está trabajando actualmente. La #endregion especifica el final de un bloque de código #region.

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