Work with comment and compound statements
When you're writing code for any programming language, it's good practice to comment on your code. A comment is a description or extra explanation in your code about your code. Comment statements aren't considered coding; the statements are only available so other developers can better understand the code that you've written.
You can comment by using two forward slashes (//), as follows:
// This is a comment
In Visual Studio Code, you can select Edit and then Toggle Line Comment (or use the Ctrl+: shortcut keys) to comment.
To comment on a whole block of code, you can use /* and */.
In Visual Studio Code, you can select Edit and then Toggle Block Comment (or use the Alt + Shift+A shortcut keys) to comment on a block of code.
/* This is a comment
on multiple
multiple
multiple
lines. */
XML Comments in Code
In Dynamics 365 Business Central, you can add documentation to your code by including XML elements in special comment fields directly in the source code before the block of code that the comment refers to.
The documentation comment must immediately precede a user-defined type that it annotates, for example a codeunit, table, or interface, or a member such as a field or method.
The syntax for adding XML comments in your code is triple slashes /// followed by one of the supported XML tags.
There's IntelliSense support for writing documentation comments. Most importantly providing a template documentation comment when writing the third slash in the triple slash.
Documentation comments are visible when hovering over source symbols, in completion lists, and in signature help.
By adding XML comments in code, you can improve readability, add useful information about the implementation, and help others take over code that you wrote. With XML comments you also enable IntelliSense in Visual Studio Code on the AL objects that you add in your code as a help to other developers, working with or extending your code. This means that when you have built an extension and someone extends this code, they'll get inline documentation when they call the given object.
You can find more information about Supported XML tags.
The following example is taken from the Email.Codeunit.al file in the
System Application. In this example, the parameter EmailMessageId is
documented using the <param> syntax.
/// <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;
...
For special symbols, such as angle brackets, to appear in text of a documentation
comment, use the HTML encoding of < and > which is < and > respectively.
The following example illustrates how to do this.
/// <summary>
/// This property always returns a value < 1.
/// </summary>
Code comments improve the readability of the code that you've developed and they are very useful for anyone modifying or maintaining that code. Furthermore, code comments form the basis of auto-generated documentation.
Great code comments do the following things:
Never state the obvious.
Write a meaningful comment, use precise wording to describe why.
Imagine yourself in the shoes of the developer using this piece of code, what would you want to know?
For properties and methods, use active wording such as Sets..., Gets..., and Specifies..., and then explain what it does.
List all pre-conditions for your parameters (can' be null, must be within a certain range, and so on).
List any post-conditions that could influence how callers deal with return values.
List any exceptions the method may throw (and under what circumstances).
If similar methods exist, explain the differences between them.
Call attention to anything unexpected (such as modifying global state).
Enumerate any side-effects, if there are any.
Be consistent and concise.
Make sure that your comments are reviewed.
Code region compiler directive
Use code regions to structure related code, add documentation of code sections, and expand or collapse these for fast navigation in your code with easy outlining of the code.
Directives are a new construct in the AL language that specifies how the AL compiler treats an enclosed section of code. The same concept is known in other languages. The specific directive instructions must be supported by the compiler—you can't create custom preprocessing instructions.
The #region directive is used to mark a block of code that you can expand or collapse. This can, for example, be useful for larger files for better readability or for focusing on code that you're currently working on. The #endregion specifies the end of a #region block of code.
A #region block must be terminated with a #endregion directive. A #region block can't overlap with an #if block. However, a #region block can be nested in an #if block, and an #if block can be nested in a #region block.
In this example the #region directive makes a code block that is up for refactoring collapsible:
#region Ugly code - let's not look at this
procedure UglyCode()
begin
// No one should look at this
end;
#endregion
Example of defining regions in a code unit:
Example of collapsing regions:
Compound Statements
A compound statement is one statement that consists of multiple statements. Compound statements are indicated by begin and end, and everything in between is one compound statement.
begin
statement 1;
statement 2;
statement 3;
...
end