Documentation Guidelines

Write comments and documentation in US English (AV2301)

Document all public, protected and internal types and members (AV2305)

Good functional documentation allows Visual Studio, Visual Studio Code or Jetbrains Rider to display the documentation when your class is used somewhere else. Furthermore, by properly documenting your classes, tools can generate professionally looking class documentation.

See also AV2306

[!IMPORTANT] Exception: Sometimes the purpose is so obvious that the documentation would become repetitive. Don’t do that.

[!NOTE] You don’t need to use /// <inheritdoc/> on overriding or implementing members. Visual Studio and Rider will automatically inherit documentation from the base type or interface.

Write XML documentation with other developers in mind (AV2306)

Write the documentation of your type with other developers in mind. Assume they will not have access to the source code and try to explain how to get the most out of the functionality of your type.

Document the purpose of a member, instead of describing its implementation (AV2308)

A member’s name should describe its intent from a consumer perspective. Documentation should provide the why and the what, not describe the internals.

Instead of:

/// <summary>
/// Iterates over the list and sets IsActive to false for each item.
/// </summary>
public void Deactivate(IEnumerable<Item> items)

write:

/// <summary>
/// Marks all items as inactive so they are excluded from future processing.
/// </summary>
public void Deactivate(IEnumerable<Item> items)

Documentation that simply restates the implementation gives no extra value and becomes a maintenance burden when the implementation changes.

Avoid inline comments (AV2310)

If you feel the need to explain a block of code using a comment, consider replacing that block with a method with a clear name.

Only write comments to explain complex algorithms or decisions (AV2316)

Try to focus comments on the why and what of a code block and not the how. Avoid explaining the statements in words, but instead help the reader understand why you chose a certain solution or algorithm and what you are trying to achieve. If applicable, also mention that you chose an alternative solution because you ran into a problem with the obvious solution.

Don’t use comments for tracking work to be done later (AV2318)

Annotating a block of code or some work to be done using a TODO or similar comment may seem a reasonable way of tracking work-to-be-done. But in reality, nobody really searches for comments like that. Use a work item tracking system to keep track of leftovers.