XML comments style guidelines

In CoreFX we didn’t call out a standard for XML comments. Since we have so much active cleanup and code generation I think we should develop some consistency guidelines, with the following goals:

Goals (in priority order)

1. Code style is consistent
2. Comments are readable
3. Comments are maintainable
4. Comments have real value

Here are some starting guidelines for discussion:

Guideline 1: Use XML style comments for methods and classes.

// DO

/// <summary>
///  Start the timer.
/// </summary>
public void Start() {}

// DO NOT

// Start the timer.
public void Start() {}

Guideline 2: Indent tag content by one extra space (two total) when on separate lines for readability.

// PREFER

/// <summary>
///  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
///  labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
///  laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in
///  voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat
///  non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
/// </summary>

// AVOID

/// <summary>
/// Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
/// labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
/// laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in
/// voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat
/// non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
/// </summary>

Guideline 3: Avoid adding comments that simply repeat the name of the element.

// DO NOT

/// <summary>
///  MyClass class.
/// </summary>
public class MyClass {}

Guideline 4: Use <see cref="" /> and <paramref name="" /> blocks when refering to other code elements or URLs. This helps with code navigation and will keep comments up to date when refactoring.

// DO

/// <summary>
///  Opens a handle for the given <paramref name="device"/>.
///  Use <see cref="CloseHandle(IntPtr)" /> to close the handle
///  when no longer needed.
/// </summary>
public IntPtr OpenHandle(string device) {}

// DO NOT

/// <summary>
///  Opens a handle for the given device. Use CloseHandle()
///  to close the handle when no longer needed.
/// </summary>
public IntPtr OpenHandle(string device) {}

cc: @bartonjs

[sharwell]

💡 If you want assistance in XML documentation syntax, consider adding DotNetAnalyzers.DocumentationAnalyzers to the project. It has a bunch of rules to help get things like paragraphs and lists correct, and even has a refactoring that allows a comment to initially be written as Markdown and then converted to XML syntax. More information about the specific rules can be found on its documentation page. If you have questions about any of the incomplete documentation pages please feel free to ask.

[JeremyKuhne]

We’ve settled on the above as the current working set.