Comments

Put XML comments on all publicly visible members. That means all members in a product which will include access to its source code.

References

When referencing specific namespaces/types/members, XML comments should use <see cref=""/> tags as much as possible to get highlighted in Intellisense, automatically renamed when refactoring, and automatically turned into links in the API documentation.

When referencing method parameters, use grave accents around the `parameterName` (the ` / ~ key is found between Esc and Tab on most keyboards). The <paramref name="key"/> tag is unnecessary since Visual Studio currently (2019) doesn't show such parameters in any special way and the comment is right above the parameters so keeping them in sync isn't really a problem.

Links

Links inside XML comments should be formatted as <see href="URL">Display Text</see> (note the href rather than the cref usually used in see tags). This gives decent readability across all views:

  • In Visual Studio Intellisense, the Display Text is highlighted like a hyperlink (though it's not actually a hyperlink because it's displayed in a tooltip which can't be clicked).
  • In API documentation generated by a tool like Wyam it can be displayed as a proper hyperlink.
  • The text in the source code is not the most readable, but the link can easily be opened from there as well.

Tags

Certain tags can be inserted at the start of an XML comment summary to clearly indicate certain differences from other members. In a multi-line comment, such tags are the only thing placed on the same line as the opening summary tag:

/// <summary>[Editor-Only]
/// Why the hell is the syntax highlighting making the comment tags blue?
/// </summary>
Tag Description
[???-Only] Only exists when the prefix is defined, otherwise any attempt to use this feature will give a compiler error.
[???-Conditional] Uses the [Conditional] attribute so that any calls to such a method will be automatically removed when the prefix is not defined.
[Editor-???] Only available in the Unity Editor. Uses UNITY_EDITOR as the conditional compilation symbol.
[Assert-???] Available in the Unity Editor and Development Builds. Uses UNITY_ASSERTIONS as the conditional compilation symbol.
[Pro-Only] Only available in the Pro version of the plugin in question.
[Internal] Part of the internal workings of the plugin and only exposed as a necessity. Not recommended for external use unless you know what you are doing.
[??? Extension] An Extension Method added by the named plugin.

Member Separators

Comment lines consisting of a forward slash followed by 120 asterisks and another slash are used to group related members together such as fields wrapped by a property or multiple overloads of the same method.

  • This helps improve code readability, particularly by more clearly delineating code at the class level from that nested inside methods.
  • The effect is a bit less useful in professional API code with XML comments on everything, but is still worthwhile.
  • The number 120 was chosen as it fits nicely on 1920x1080 monitors with room to spare for other views such as the Solution Explorer.

/************************************************************************************************************************/

Put #regions between two such separator lines like so:

/************************************************************************************************************************/ #region My Code /************************************************************************************************************************/