Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-10-07 23:56:56 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add 18 more community AL/BC patterns across appsource, data-modeling, error-handling, security, style, testing, ui, upgrade, and web-services

Browse source 
Second contribution from CURABIS ApS, generalized from patterns observed across real AppSource/PTE development. Cross-checked against the current microsoft/knowledge corpus before opening; several originally-drafted candidates were dropped as duplicates of existing files.
This commit is contained in:
Michael Dieringer 2026-09-04 20:59:54 +02:00
parent 07e324ddbc
commit a4d85c3e9e
50 changed files with 1262 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

30
microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.md Normal file
View file

@ -0,0 +1,30 @@
---
bc-version: [all]
domain: style
keywords: [comments, verbosity, self-documenting, restate, tutorial-style]
technologies: [al]
countries: [w1]
application-area: [all]
---
# Comments must not restate what the code already shows
## Description
A comment above nearly every statement that just narrates what the statement already says (`// Validate the customer number` above `SalesHeader.Validate("Sell-to Customer No.", CustomerNo)`) adds noise without adding information. Production AL — the Base Application, mature partner codebases — is comment-sparse by comparison: identifiers do the explaining, and a comment appears only when the code alone can't carry the reason.
A comment earns its place only when it captures something the code cannot: a non-obvious business rule, a workaround for a specific platform limitation, or a constraint that would surprise the next reader. If removing the comment would leave the reader no worse off, the comment should not have been written.
This does not override required structural documentation — feature/scenario test tags and XML-doc summaries on public library procedures remain required where they apply; those are structural markers, not narrative comments.
## Best Practice
Let the code speak for itself; reserve comments for the reason a reader could not otherwise infer.
See sample: `al-comments-must-not-restate-what-code-already-shows.good.al`.
## Anti Pattern
A comment line before every statement, repeating in English what the statement's own identifiers already say.
See sample: `al-comments-must-not-restate-what-code-already-shows.bad.al`.