While browsing the MSDN documentation for the .NET Framework Class Library (FCL) I've always been amazed by how consistent and fully documented it is. It's a constant companion when developing .NET applications. Most doubts that arise when using the APIs are covered. The contrast with e.g. the older Win32 documentation is striking.

Some examples:

  • Documentation for properties always starts out with either "Gets" or "Gets or sets" to specify accessors.
  • Type parameters start out with: "The type of ...".

Does Microsoft use a documentation convention which is followed for the FCL? If so, is this convention publicly available for me to use as well?

  • Microsoft publishes the standard for all Microsoft .NET languages.
    – Ramhound
    Commented May 14, 2012 at 16:09
  • @Ramhound: In this case, the standard applies to the language only, not the documentation. Commented May 14, 2012 at 16:39
  • 1
    To address a few issues: Documentation questions are on-topic here on Programmers. Questions about where to obtain specific style guidelines are also on-topic, if they don't appear to be readily available (meaning by a couple of quick searches using your favorite search engine). It's also clear that some languages provide style guidelines for in-code documentation. I don't see any problems with this question at all.
    – Thomas Owens
    Commented May 14, 2012 at 16:46
  • 1
    The closest I found is a brief example within the subtopics of msdn.microsoft.com/en-us/library/b2s063f7.aspx (specifically msdn.microsoft.com/en-us/library/z04awywx.aspx). Commented May 14, 2012 at 17:11
  • 2
    Looking at the .net documentation I'm always amazed how they manage to put so much boilerplate and so little substance in there. IMO the Win32 API documentation is much better that the .net documentation. Commented May 14, 2012 at 22:09

1 Answer 1


Yes. There is a spec of sorts. That spec is built into StyleCop.

What it basically does is turn "style" errors (comments, code layout/formatting etc.) into build errors.

You can also include/exclude any rule that you like.


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.