C# Documentation Standards · CS-07

Documenting your code allows Visual Studio to pop-up the documentation when your class is used somewhere else. Furthermore, by properly documenting your classes, tools can generate professionally looking class documentation.

Write the documentation of your type with another developer in mind. Assume he or she will not have access to the source code and try to explain how to get the most out of the functionality of your type. Following the MSDN on-line help style and word choice helps the developer to find its way through your documentation more easily.

NOTE: This rule becomes a MUST in the following cases:

• The code is being shipped in a library, e.g. as an assembly in a NuGet package
• The class, method or property is referenced by Swagger to generate API documentation, e.g. a controller action, or the property on a class that is a parameter to a controller action

Roslyn Analyzer Rule SA1600

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.

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 such as Azure DevOps to keep track of left overs.

Roslyn Analyzer Rule AV2318