Coding Standard

"First, your return to shore was not part of our negotiations nor our agreement so I must do nothing. 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, Miss Turner!"

  • Hector Barbossa, Pirates of the Caribbean.

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 Functions 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.
Preprocessor Directive MACRO_CASE Only used by the compiler, which is very different from regular code that gets executed as the program runs. Also, any ! symbol should have a space between it and the target since that character is easy to miss among upper case letters, e.g. #if ! UNITY_EDITOR.

File Naming

  • Script file names should match the main type they contain. This is mandatory for anything inheriting from UnityEngine.Object, but is also a good practice in general.
  • When using a partial type to declare a nested type in a separate file from the main script, the script should be named in the same way it would appear when accessing the nested type externally, i.e. OuterType.InnerType.cs.
  • If a generic type shares the same name as a non-generic type, the generic file should have a T suffix, i.e. TypeNameT.cs.
  • If multiple generic classes share the same name, their file names should have a numerical suffix indicating the number of generic parameters they have, i.e. StateMachine<TState> is in StateMachine1.cs and StateMachine<TKey, TState> is in StateMachine2.cs.


Put XML comments on all publicly visible members. That means all members in 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.

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.

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
[???-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 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 about the features this applies to.
[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.
[Animancer Extension] An Extension Method added by Animancer.

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