Enumerate any side-effects, if there are any.Call attention to anything unexpected (such as modifying global state).If similar methods exist, explain the differences between them.List any exceptions the method may throw (and under what circumstances).List any post-conditions that could influence how callers deal with return values.List all pre-conditions for your parameters (can't be null, must be within a certain range, and so on).For properties and methods, use active wording such as Sets., Gets., and Specifies., and then explain what it does.Imagine yourself in the shoes of the developer using this piece of code, what would you want to know?.

Write a meaningful comment, use precise wording to describe why.Great code comments must do the following:

Furthermore, code comments form the basis of auto-generated documentation. / This property always returns a value < 1.Ĭode comments improve the readability of the code that you've developed and they're useful for anyone modifying or maintaining that code.

/ Enqueues an email in the outbox to be sent in the background.įor special symbols, such as angle brackets, to appear in text of a documentation comment, use the HTML encoding of, which is < and > respectively.

/ Provides functionality to create and send e-mails. In this example, the parameter EmailMessageId is documented using the syntax. The following example is taken from the file in the System Application. Specifies a list formatted as a bulleted or numbered list, or as a table in a or block. Specifies that multiline text within a description should be marked as code inside a top-level tag. Specifies that text within a description should be marked as code inside a top-level tag. Specifies a reference to a parameter in a or block.Īllows structuring text inside a, , or tag.Īllows formatting text as bold inside a top-level tag.Īllows formatting text as italic inside a top-level tag. Used to supplement information given in the section. Used to specify an example of how to use a given codeunit or object. Used in method declarations to describe the return value of the method.

For each parameter, specify the name and a description. Used in method declarations to describe one or more parameters defined in the method. The following table lists the XML elements that are supported for AL.

If you have the allowDownloadingSource setting in the app.json file set to false and you then download an app package the app package won't contain any XML comments. When your code is documented using XML comments, it means that when you've built an extension and someone extends this code, they'll get inline documentation when they call the given object. With XML comments, you also enable IntelliSense in Visual Studio Code on the AL objects that you add in the code as a help to other developers, working with or extending your code. 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. There's IntelliSense support for writing documentation comments that also provides a template comment on entering the third slash in the triple slash.ĭocumentation comments are visible when you hover over source symbols, in completion lists, and in signature help. The syntax for adding XML comments in your code is triple slashes /// followed by one of the supported XML tags. The documentation comment must immediately precede a user-defined type that it annotates, for example a codeunit, table, interface, or a member such as a field or method. In Dynamics 365 Business Central, you can add documentation directly in your source code by including XML elements in special comment fields before the block of code that the comment refers to. APPLIES TO: Business Central 2020 release wave 2 and later

Never read the comments