Coding Guidelines

This page documents the coding guidelines in SEE. It serves as a checklist for code reviews. Reviewers should check conformance to these rules.

This list is by no means considered complete. Feel free to expand it.

Documentation

• Every declaration including private and protected ones must be documented in the C# documentation comments style.
• All parameters and the return type of a method must be documented. The summary must state preconditions explicitly (e.g., whether or not a parameter may be null).
• Every namespace must be documented. A namespace containing code developed by SEE must be under the root namespace SEE or one its descendants. The physical directory structure of code and the logical namespace structure must be the same. If there is a namespace SEE.X.Y there must be a file Y.cs in the directory SEE.X.Y that contains the declaration of the name space with an empty body. In front of the keyword namespace there must be a C# summary comment explaining the purpose of this namespace.

Code Formatting

• The code is formatted using Visual studio's style. Use Ctrl-K F to format your code.

• Do not use trailing whitespace at the end of a line. Trailing whitespace is unnecessary and is a source of potential merge conflicts and superflous code differences. There is a plug-in for visual studio named RemoveTrailingWhitespaces that removes trailing whitespace when a file is saved.

• Use only \n for line endings.

Visibility modifiers public, internal, protected, private

• Whenever possible, declarations should be made private.
• internal should be preferred over public. Note the visiblity rules in C#: public declarations will be visibile across assemblies, while internal declarations are visibile only within the same assembly. SEE is not a library, so everything could be declared internal, unless, however, it is used by editor or test code which are in other assemblies.

Naming Conventions

• You shall use the discard _ for an unused parameter, if the parameter cannot be avoided (e.g., because the signature is dictated by Unity).
• Names must be meaningful. E.g. tmp is no meaningful name. An exception are loop-iteration variables, which may be named i or j etc.
• Names must be in CamelCase. Do not use _ as a separator within an identifier.
• Private fields must start with a lower-case letter, protected, internal and public fields with upper-case letter. This holds for constant and readonly declarations, too.
• The name of an interface must start with a capital I. The subsequent letter must upper case, too.
• Names of all kinds of methods (static, non-static, including local functions) and properties must start with a capital letter (i.e., must conform to PascalCase).

Coding

• Explicit typing is always preferred. Names must not start with an underscore. Keyword var should be avoided. It may, however, be used to iterate on key/value pairs of dictionaries (not on keys or values alone).
• Curly brackets must always be used in conditional statements (if and all sorts of loops) even if they are optional when there is only one nested statement.

Third-Party Components

All third-party components must have licenses compatible with the MIT license (SEE is under MIT). The license and original source must be documented. If the original authors have not provided this information, it should be put into a readme file at the top level of the directory where third-party component was stored.

Third-party components should not be contained in folder SEE. Remember the rule that the physical directory structure should reflect the logical namespaces. If third-party components were part of SEE, they should be contained in namespace SEE. We want a clear separation between code written by us and code imported from another source.

An exception to this rule may be very small components, e.g., a single file. The original source and license must be made explicit in this file.

All third-party components should be contained in folder Assets/Plugins at top level. To ease later integrations of updates of these third-party components, changes to the imported code should be kept to a minimum.