When we are creating or modifying software, we should always document what we have done. It is often difficult for developers to spend much time (or, money) on documentation because many don't enjoy doing it and the benefits are uncertain. A reasonable goal is to provide enough documentation so that a knowledgeable person following us can understand what we have done as well as the reasons why.

If we choose good variable names, the C/AL code will tend to be self-documenting. If we lay out our code neatly, use indentation consistently, and localize logical elements in functions, then the flow of our code should be easy to read. We should also include comments which describe the functional reason for the change. This will help the next person in this code to not only be able to follow the logic of the code, but to understand the business reasons for it as well.

In case of a brand-new function, a simple statement of purpose is often all that is necessary. In case of a modification, it is extremely useful to have comments providing a functional definition of what the change is intended to accomplish, as well as a description of what has been changed. If there is external documentation of the change, including a design specification, the comments in the code should refer to this external documentation.

In any case, the primary focus should be on the functional reason for the change, not just the technical reason. Any good programmer can study the code and understand what was changed, but without the documentation describing why the change was made, the task of the next person to maintain or upgrade that code will be made much more difficult.

In the following example, the documentation is for a brand-new report. The comments are in the Documentation section, where there are no format rules, except for those we impose. This is a new report, which we created in Chapter 6, Introduction to C/SIDE and C/AL. The comment is coded to indicate the organization making the change (in this case CD) and a sequence number for this change. In this case, we are using a two digit number (06) for the change, plus the version number of the change, 00; hence, we start with CD.06.00, followed by the date of the change. Some organizations also include an identifier for the developer in the Documentation section comments.

We can make up our own standard format that will identify the source and date of the work, but we should have a standard and use it. When we add a new data element to an existing table, the Description property should receive the same modification identifier that we would place in the code comments.

When we make a subsequent change to an object, we should document that change in the Documentation trigger and also in the code, as described earlier.

Inline comments can be made in two ways. The most visible way is to use a // character sequence (two forward slashes). The text that follows the slashes on that line will be treated as a comment by the compiler; it will be ignored. If the comment spans multiple physical lines, each line of the comment must also be preceded by two forward slashes.

In the following image we have used // to place comments inline to identify a change:

Here we have made the modification version number 01, resulting in a change version code of CD.07.01. In the following code, modifications are highlighted by bracketing the additional code with comment lines containing the modification identifier, and start and end text indicators. Published standards do not include the dashed lines shown here, but doing something that makes comments stand out makes it easier to spot modifications when we are visually scanning the code.

A second way to place a comment within the code is to surround the comment with a matched pair of braces { }. Because braces are less visible than the slashes, we should use // when our comment is relatively short. If we decide to use { }, it's a good idea to insert a // comment at least at the beginning and end of the material inside the braces, to make the comments more visible. Some experienced developers recommend using // on all removed code lines, to make the deletions easier to spot later. Evolving standards recommend against any use of the braces for commenting out code.

For example:

{//CD.07.02 start deletion -------------
//CD.07.02 Replace validation with a call to an external function
...miscellaneous C/AL validation code
//CD.07.02 end deletion ------------- }

When we delete code that is part of the original Microsoft distribution, we should leave the original statements in place but commented out, so the old code is inoperative (an exception to this may apply if a source code control system is in use which tracks all the changes). The same concept applies when we change the existing code; leave the original code in place, but commented out, with the new version being inserted as shown in the following screenshot. This approach does not necessarily apply to code that we ourselves created originally.

Comment Selection and Uncomment Selection options have been added to the Edit menu option list in NAV 2015. When we are commenting or uncommenting large chunks of code, these can be useful. See the Help C/AL Comments.

When we make changes such as these, we don't want to forget to also update the object version numbers located in the Version List field on the Object Designer screen. It's also a good idea to take advantage of one of the previously mentioned source code management tools to track modifications.

From our previous experience, we know that the format of the internal documentation is not what's critical. What is critical is that the documentation exists, is consistent in format, and accurately describes the changes that have occurred. The internal documentation should be a complement to external documentation which defines the original functional requirements, validation specifications, and recommended operating procedures.

Yet another approach, one that is especially suitable for modifications that exceed a small number of lines of code or which will be called from multiple places, is to create a new function for the modification, name the function so that its purpose is obvious, then call the function from the point of use. In this case, that function might be named something like CheckDatePrizeLastWon and would contain the C/AL code shown earlier, specifically IF (WORKDATE - "Last Prize Date") < 30 THEN CurrReport.SKIP. In this case, the function would only have one line of code (not a good example), we would pass in the Last Prize Date value and the function would return a Boolean value telling us whether or not the individual was eligible for a new prize.