- Don’t overdo documentation as it can do more harm than use when going out of date, what 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 as you write code: Use correct grammar and punctuation (remember that comments are sentences), adhere to style conventions.
Follow C# XML comment guidelines. C# keywords referenced in XML comments like
trueshould be wrapped into a
/// <returns>Returns <see langword="true"/> on success, <see langword="false"/> otherwise.</returns>
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!