Create a separate set of rules for Library code versus Web Applications

[j2jensen]

Similar to how we're using different baseline rulesets for Test projects, there are a couple of rules that should probably be suppressed for most of our web applications, but preserved for library applications.

1. Requiring the ClsCompliant attribute.
2. Requiring documentation to exist for all members. (This only becomes an issue when you set the project to export XmlDoc output on build, which would normally be reserved for libraries anyway, but several web applications do this in order to generate Swagger docs.)
3. Do not directly await a Task without calling ConfigureAwait. This only becomes problematic if someone blocks on the resulting task somewhere in the call chain, while using a Synchronization Context that only allows one thread to be running at a time. In web applications, we are usually able to ensure that we're using async/await throughout the entire call chain. In utility libraries, we don't have as much say regarding how the Task gets used upstream. There's also a general assumption that utility libraries won't be relying on data tied to the current SynchronizationContext, like HttpContext.Current, whereas web applications might.

Let's create a set of rules for Library code that considers these issues to be errors, and a set of rules for Web Applications that ignores them.

Then we should also update the Wiki, which has a note on CA1014: Mark Assemblies CLS Compliant.

[braydengramse]

The StyleCop Analyzers have many different rules for how detailed your documentation should be. How strict do we want to be?

SA0001: XML comment analysis disabled SA1004: Documentation lines should begin with single space SA1600: Elements should be documented SA1601: Partial elements must be documented SA1602: Enumeration items must be documented SA1603: Documentation must contain valid XML SA1604 Element documentation must have summary SA1605: Partial element documentation must have summary SA1606: Element documentation must have summary text SA1607: Partial element documentation must have summary text SA1608: Element documentation must not have default summary SA1609: Property documentation must have value SA1610: Property documentation must have value text SA1611: Element parameters must be documented SA1612: Element parameter documentation must match element parameters SA1613: Element parameter documentation must declare parameter name SA1614: Element parameter documentation must have text SA1615: Element return value must be documented SA1616: Element return value documentation must have text SA1617: Void return value must not be documented SA1618: Generic type parameters must be documented SA1619: Generic type parameters must be documented partial class SA1620: Generic type parameter documentation must match type parameters SA1621: Generic type parameter documentation must declare parameter name SA1622: Generic type parameter documentation must have text SA1623: Property summary documentation must match accessors SA1624: Property summary documentation must omit set accessor with restricted access SA1625: Element documentation must not be copied and pasted SA1626: Single line comments must not use documentation style slashes SA1627: Documentation text must not be empty SA1628: Documentation text must begin with a capital letter SA1629: Documentation text must end with a period SA1630: Documentation text must contain whitespace SA1631: Documentation must meet character percentage SA1632: Documentation text must meet minimum character length SA1642: Constructor summary documentation must begin with standard text SA1643: Destructor summary documentation must begin with standard text SA1644: Documentation headers must not contain blank lines SA1645: Included documentation file does not exist SA1646: Included documentation XPath does not exist SA1647: Included node does not contain valid file and path SA1648: Inherit doc must be used with inheriting class SA1650: Element documentation must be spelled correctly SA1651: Do not use placeholder elements

[j2jensen]

My votes:

SA0001: XML comment analysis disabled SA1600: Elements should be documented SA1601: Partial elements must be documented SA1602: Enumeration items must be documented SA1604 Element documentation must have summary SA1605: Partial element documentation must have summary SA1606: Element documentation must have summary text SA1607: Partial element documentation must have summary text SA1608: Element documentation must not have default summary

• Error for library projects, None for everything else

SA1004: Documentation lines should begin with single space

• Error. This should be automated by our Resharper auto-format settings

SA1603: Documentation must contain valid XML

• Error.

SA1609: Property documentation must have value SA1611: Element parameters must be documented SA1615: Element return value must be documented SA1618: Generic type parameters must be documented

• None. Developers can decide whether it makes sense to add specific elements like these.

SA1610: Property documentation must have value text SA1612: Element parameter documentation must match element parameters SA1613: Element parameter documentation must declare parameter name SA1614: Element parameter documentation must have text SA1616: Element return value documentation must have text SA1617: Void return value must not be documented SA1619: Generic type parameters must be documented partial class SA1620: Generic type parameter documentation must match type parameters SA1621: Generic type parameter documentation must declare parameter name SA1622: Generic type parameter documentation must have text SA1623: Property summary documentation must match accessors SA1624: Property summary documentation must omit set accessor with restricted access SA1625: Element documentation must not be copied and pasted SA1645: Included documentation file does not exist SA1646: Included documentation XPath does not exist SA1647: Included node does not contain valid file and path SA1648: Inherit doc must be used with inheriting class

• Error. If devs choose to include these documentation elements, they should at least make sure they're correct.

SA1626: Single line comments must not use documentation style slashes SA1627: Documentation text must not be empty SA1628: Documentation text must begin with a capital letter SA1629: Documentation text must end with a period SA1630: Documentation text must contain whitespace SA1631: Documentation must meet character percentage SA1632: Documentation text must meet minimum character length SA1642: Constructor summary documentation must begin with standard text SA1643: Destructor summary documentation must begin with standard text SA1644: Documentation headers must not contain blank lines SA1651: Do not use placeholder elements

• Error. These all seem like reasonable style rules to enforce.

SA1650: Element documentation must be spelled correctly

• I could see this one becoming annoying, but I'd probably start with it enabled and see what the signal-to-noise ratio is like.

That said, note that several of these are already disabled by the StyleCop.Analyzers package, so having them turned on may not actually have an impact for projects that aren't using a StyleCop extension: https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/KnownChanges.md#disabled-rules

[j2jensen]

Resolved by #11