Code Comment Rules in Dynamics 365 Finance & Operations
Question 37 — XML documentation headers, inline comments, and what NOT to comment.
Interview Question
Model Answer (Short)
Comments serve two purposes: an XML-formatted header that describes a class or
method (its purpose, input parameters and return value), and inline comments that explain code
which isn't self-evident. Header comments use /// on each line. An inline comment is
required when the code's intent isn't obvious, when it deviates from best practice,
or when the reasoning is complex. Any bug fix or design change should be supported by a comment
(XML syntax recommended). Crucially, you should not write historical comments — modified dates,
user names, old code, etc. — because that history belongs in source control, not the code.
The Two Purposes of Comments
1. XML header comment
- Describes the class or method in XML syntax.
- Documents the purpose, the input parameters, and the return value.
- Each line must start with
///.
2. Inline (in-code) comment — when required
- When the intent cannot be read directly from the code.
- When the code deviates from best practices.
- When the reasoning behind a decision is complex or hard to understand.
- Any bug fix or design change must be supported by a comment (XML recommended).
Formatting rules
- Write comments on a separate line, not at the end of a code line.
- Comments begin with an uppercase letter and end with a period.
- Put a space between the comment delimiter (
//) and the text. - Do not write historical comments (modified date, user, old code).
Prerequisites (Rule 5)
- Visual Studio with the Dynamics 365 developer tools.
- A custom model / package for your objects.
- Source control in place (so history lives there, not in comments).
Code Example — XML documentation header
///
/// Calculates the total amount for a sales line.
///
/// The sales line to calculate.
/// The calculated line amount.
public Amount calcLineAmount(SalesLine _salesLine)
{
return _salesLine.SalesQty * _salesLine.SalesPrice;
}Correct inline comment style
void myMethod()
{
// Loop through the counter.
for (int i = 0; i < 10; i++)
{
info(strFmt("i is %1", i));
}
}Avoid: historical / end-of-line comments
// BAD: historical comment belongs in source control, not code
// Modified 2026-06-01 by JDoe - changed from old logic
int total = qty * price; // BAD: end-of-line comment
// GOOD: separate line, explains the WHY, no history
// Apply the base price because discounts are handled downstream.
int total2 = qty * price;Good vs. Bad Commenting
| Aspect | Good | Bad |
|---|---|---|
| Header | XML /// with summary/params/returns |
No header, or plain text |
| Placement | Separate line above the code | End of the code line |
| Content | Explains the why / non-obvious logic | Restates the obvious |
| History | Kept in source control | Dates/users/old code in comments |
| Style | Uppercase start, period end, space after // | Inconsistent formatting |
Points the interviewer wants to hear
- Comments serve two purposes: XML header + inline explanation.
- Header comments use
///and document purpose, params and return. - Inline comments are required when code is non-obvious, deviates, or complex.
- Write on a separate line, uppercase start, period end, space after
//. - No historical comments — that history belongs in source control.
Likely Follow-up Questions
- Why should modification history not be written as code comments?
- What must an XML documentation header contain?
- When is an inline comment actually required?
- Why prefer a comment on a separate line over an end-of-line comment?
Key Takeaway
Use XML /// headers to document classes/methods and inline comments
to explain non-obvious, deviating or complex logic — always on a separate line with clean
formatting. Keep modification history in source control, never in the code.