Inline documentation guidelines

Edit
  • Don’t overdo documentation as it can do more harm than use when going out of date, which it tends to do.
  • Always document complex pieces of logic by briefly explaining what the code does and why.
  • Always document unusual solutions, hacks or workarounds, and explain why they are necessary.
  • It's advised to document interfaces, best with usage samples. This is especially true for services: Always document services, as these are commonly used by other developers too.
  • Never use comments for mental notes (like "TODO"). Such notes should go into more appropriate places like an issue tracker, some common documentation or something else.
  • Documentation should be as close to what it documents as possible to avoid going out of date.
  • It's good to document what the aim of a type (mostly class or interface) is. This is to be able to quickly understand what a type does without having to understand its code.
  • Write documentation just like you write code: Use correct grammar and punctuation (remember that comments are sentences), adhere to style conventions.
  • Follow C# XML comment guidelines:
    • C# keywords like true, referenced in XML comments, should be wrapped into a see element as follows: /// <returns><see langword="true"/> on success, <see langword="false"/> otherwise.</returns>
    • Generic types should be referenced as follows: <see cref="ILookup{TKey, TValue}"/>
    • As seen in the above examples, don't add a space before self-closing elements in XML comments. This is due to the way automatic tooling generates those elements, as it would be cumbersome to change every such instance.
  • Use ASCII art to visualize something in 2D.
  • There are some great tips in this blog post.

This page is part of the Orchard Dojo Library!

This page and many others here are part of the open-source, portable package of Orchard Core goodies: the Orchard Dojo Library for Orchard Core. The Library is freely accessible by anyone; just go to its repository to download its full content (you can even download the textual content of the Library as a big concatenated document in HTML), file issues or fork it! You can even edit it online on Bitbucket, just click on the Edit link in the upper right corner!

Note that the Library also has an Orchard 1.x version, check it out here!