Rules and Guidelines

Use action verbs

Start summaries with action verbs, use present tense for descriptions

Be specific

Be specific about null handling, empty collections, and edge cases

Inject domain knowledge

When you encounter domain-specific terms (e.g., GLN, SAP integration points, Polylith architecture concepts), provide brief explanations that add value without being condescending.
Skip explanations for common terms that any developer would know.

Update bad doc comments

If you come across a method that already has doc comments but they're terrible or confusing, change them!
If you think that the doc comment is not necessary at all, it is okay to remove it.
We don't want to have doc comments that waste space on developer's screens and add little to no value or additional information.

Document intent, not implementation

Focus on the "why" and "what" rather than the "how" (unless the how is particularly complex or non-obvious).

Connect the dots

Reference related components, patterns, and architectural decisions.
Help readers understand why this code exists, how it relates to other parts of the system, what patterns or principles it implements, and any important constraints or assumptions.

DO NOT use markdown in doc comments

Markdown formatting will not render correctly in IDE tooltips and documentation tools and will not be formatted correctly by code formatters.

DO NOT use manual linebreaks

Don't expect to use linebreaks inside the doc comments, they will be erased by the code reformatter, which will format instead based on the xml's structure.

Things requiring doc comments

XML doc comments are required for:

Public classes
Public methods
Public properties
Complex private methods

XML Doc Comment Reference

Below is a list of some of the xml elements you can use in C# doc commments:

<summary> - Concise overview of the member's purpose
<remarks> - Additional context, usage notes, or architectural decisions
<param> - Describe each parameter's purpose and constraints
<returns> - Explain what is returned and under what conditions
<exception> - Document all exceptions that can be thrown
<example> - Provide code examples for complex APIs
<see> and <seealso> - Cross-reference related types and members
<typeparam> - Document generic type parameters
<value> - Describe property values and their significance
<inheritdoc> - Inherit documentation from base classes/interfaces where appropriate

Documentation