DocumentationCop on ALCops

Commit requires a comment explaining why (DC0001)

Mon, 01 Jan 0001 00:00:00 +0000

Using Commit() in AL code breaks the implicit transaction model and should be rare. When a commit is genuinely required, it must be accompanied by a comment explaining why the commit is necessary.

Without documentation, future maintainers cannot determine whether the commit is intentional or accidental, making it difficult to refactor or audit the code safely.

Example

The following code uses Commit without explanation:

codeunit 50100 MyCodeunit
{
 procedure MyProcedure()
 begin
 Commit(); // Commit requires a comment explaining why [DC0001]
 end;
}

To fix this, add a comment explaining why the commit is necessary:

Writing to a FlowField requires a comment explaining why (DC0002)

Mon, 01 Jan 0001 00:00:00 +0000

FlowFields are calculated fields whose values are derived from other data and are not stored directly. Writing to a FlowField is an unusual operation that the platform does not automatically persist. When such an assignment is made intentionally, it must be accompanied by a comment explaining the rationale and how the value is handled.

Without documentation, this pattern appears to be a mistake and will confuse future maintainers.

Example

The following code assigns a value to a FlowField without explanation:

Empty statement requires a comment explaining why (DC0003)

Mon, 01 Jan 0001 00:00:00 +0000

An empty statement (a lone semicolon or an empty begin...end block) is often a sign of incomplete code or a mistake. When an empty statement is intentional, it must be accompanied by a comment explaining why the statement is deliberately empty.

Without documentation, reviewers and maintainers cannot distinguish between intentional no-ops and forgotten implementations.

Example

The following code has an empty statement without explanation:

codeunit 50100 MyCodeunit
{
 procedure MyProcedure()
 begin
 if SomeCondition then
 ; // Empty statement requires a comment explaining why [DC0003]
 end;
}

To fix this, add a comment explaining the intent:

Public procedure requires XML documentation (DC0004)

Mon, 01 Jan 0001 00:00:00 +0000

Public procedures form the API surface of a codeunit. They should be documented with XML documentation comments to describe their purpose, parameters, and return values. This helps consumers of the API understand how to use the procedure correctly.

Note: This rule is disabled by default. Enable it in your project’s .editorconfig or ruleset file if you want to enforce XML documentation on public procedures.

Example

The following public procedure lacks XML documentation:

XML documentation must match procedure signature (DC0005)

Mon, 01 Jan 0001 00:00:00 +0000

When XML documentation is provided for a procedure, it must accurately reflect the procedure’s signature. Parameters documented in XML must exist in the procedure, and all procedure parameters should be documented. Similarly, the return value documentation must match whether the procedure actually returns a value.

Inconsistent documentation is worse than no documentation because it misleads consumers of the API.

Example

The following procedure has XML documentation that doesn’t match its signature: