Coding Standard

"And secondly, you must be a pirate for the pirate's code to apply and you're not. And thirdly, the code is more what you'd call "guidelines" than actual rules. Welcome aboard the Black Pearl"

  • Hector Barbossa.

Name Composition

The following naming conventions are designed to provide a clean and consistent public API and to provide additional clarity of purpose and scope for variables.

Use PascalCase for namespace, type (class, struct, interface, enum, delegate), property, method, event.

The naming convention of variables varies based on their encapsulation:

Type Capitalisation Reason
Const PascalCase Very similar to a read-only property.
Read-Only PascalCase Same as const.
Non-Public Field _PascalCase Not meant to be externally visible (users should never see an underscore) but still has a wider scope than most other variables depending on the actual access modifier.
Public Field camelCase Is externally visible and can be get/set very efficiently and without immediate side effects, unlike a property which can run potentially expensive calculations or trigger any other code when set.
Parameter camelCase Similar to a public field, but within a smaller scope.
Local Variable camelCase Similar to a parameter, but within a smaller scope.

Comments

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

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

Comment 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
[Editor-Only] Only available in the Unity Editor. Trying to use it in runtime code will give an error so you need to put a #if UNITY_EDITOR region around your code.
[Editor-Conditional] Only available in the Unity Editor, but uses the [Conditional] attribute so that any calls to such a method will be entirely removed from runtime builds.
[Assert] Only available when the UNITY_ASSERTIONS symbol is defined (in the Unity Editor and Development Builds). It uses the [Conditional] attribute so that any calls to such a method will be entirely removed when that symbol isn't defined.
[Pro-Only] Only available in Animancer Pro, though Animancer Lite will allow it to be used in the Unity Editor (but not in runtime builds). See the Feature Comparison for more details.
[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.

Comment 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 modern 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 /************************************************************************************************************************/