Trabajar con instrucciones compuestas y de comentario
Al escribir código para cualquier lenguaje de programación, se recomienda realizar comentarios en el código. Un comentario es una descripción o explicación adicional en el código sobre este. Las instrucciones de comentario no se consideran codificación; las instrucciones solo están disponibles para que otros desarrolladores puedan comprender mejor el código que ha escrito.
Puede realizar comentarios mediante dos barras diagonales (//), de la siguiente manera:
// This is a comment
En Visual Studio Code, puede seleccionar Editar y luego Alternar comentario de línea (o usar las teclas de método abreviado Ctrl+:) para comentar.
Para comentar un bloque completo de código, puede usar /* y */.
En Visual Studio Code, puede seleccionar Editar y luego Alternar comentario de bloque (o usar las teclas de método abreviado Alt+Mayús+A) para comentar un bloque de código.
/* This is a comment
on multiple
multiple
multiple
lines. */
Comentarios XML en el código
En Dynamics 365 Business Central, puede agregar documentación a su código al incluir elementos XML en campos de comentarios especiales directamente en el código fuente antes del bloque de código al que hace referencia el comentario.
El comentario de la documentación debe preceder inmediatamente a un tipo definido por el usuario que anota, por ejemplo, una codeunit, una tabla o una interfaz, o un miembro como un campo o un método.
La sintaxis para agregar comentarios XML en su código es triple barra /// seguido de una de las etiquetas XML admitidas.
IntelliSense cuenta con soporte para escribir comentarios de documentación. Lo más importante es proporcionar un comentario de documentación de la plantilla al escribir la tercera barra en la barra triple.
Los comentarios de documentación son visibles al pasar el cursor por los símbolos de origen, en las listas de finalización y en la ayuda de la firma.
Al añadir comentarios XML en el código, puede mejorar la legibilidad, añadir información útil sobre la implementación y ayudar a otros a hacerse cargo del código que haya escrito. Con los comentarios XML, también habilita IntelliSense en Visual Studio Code en los objetos de AL que decida añadir 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.
Puede encontrar más información sobre Etiquetas XML compatibles.
El siguiente ejemplo se toma del archivo Email.Codeunit.al en la aplicación del sistema. En este ejemplo, el parámetro EmailMessageId se documenta mediante la sintaxis <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 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 < 1.
/// </summary>
Los comentarios de código mejoran la legibilidad del código que ha desarrollado y resultan muy útiles para cualquiera que modifique o mantenga ese código. Además, los comentarios de código forman la base de la documentación generada automáticamente.
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.
Directiva del compilador de región 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.
Las directivas son una nueva construcción en el lenguaje AL que especifica la manera en que el compilador AL trata una sección de código adjunta. El mismo concepto se conoce en otros lenguajes. El compilador debe admitir las instrucciones específicas de la directiva; no puede crear instrucciones de preprocesamiento personalizadas.
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.
Una bloque #region debe terminar con una directiva #endregion. Un bloque #region no puede superponerse con un bloque #if. Sin embargo, un bloque #region se puede anidar en un bloque #if, y un bloque #if se puede anidar en un bloque #region.
En este ejemplo, la directiva #region hace que un bloque de código que se puede refactorizar sea contraíble:
#region Ugly code - let's not look at this
procedure UglyCode()
begin
// No one should look at this
end;
#endregion
Ejemplo de definición de regiones en una codeunit:
Ejemplo de contracción de regiones:
Instrucciones compuestas
Una instrucción compuesta es una instrucción que consta de varias instrucciones. Las instrucciones compuestas se indican mediante begin y end, y todo lo demás es una instrucción compuesta.
begin
statement 1;
statement 2;
statement 3;
...
end