The various types of Orchard learning resources available here want to help you further enhance your Orchard skills.

Latest resource by the community

Recently updated in the Orchard Dojo Library

  • Inline documentation guidelines

    • 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.

    < More >