Resources

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

  • Code styling

    If there length of the parameter list for a method is too long to read conveniently in terms of line length (due to the 3-argument rule this should rarely happen for methods but constructors with dependency injection) break it into multiple lines parameter by parameter.

    < More >

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