BHoM's coding style and conventions
General C# conventions
Our coding style generally follows the Microsoft guidelines on C#.
However, to attain a higher level of clarity and transparency, BHoM code also adheres to additional customised rules and style guidelines.
BHoM code also adheres to customised rules and style guidelines. These are in place for several reasons, mainly:
- to make easier to read and contribute to the codebase;
- to ensure the functionality can be correctly exposed to the UIs;
- to organise functionality and classes in a tidy, easy-to-find manner.
Access modifiers specify the accessibility level of type and type members. They denote whether a type or member can be used by other code in the same assembly, and in other assemblies.
- In line with BHoM's focus on clarity and transparency, we generally use the
publicaccess modifier, which allows a type or member to be accessed by any other code in the same assembly or other assembly that reference it.
- When absolutely necessary, we use the
privateaccess modifier to limit the access of a type or member to only code in the same class.
- Although C# provides many access modifiers, we limit our use to the two mentioned above.
Filenames, objects and methods
.csfile can contain only 1 (one)
class, and there is no concept as a
- For oM objects the name of the
.csfile is the Name (excluding the namespace) of the Object (class), e.g. the
Lineclass is in the
- For engine methods, a file can only contain methods whose name start or end with the name of their file file, e.g.
Flip(Arc arc)are in the same file
FilterOpeningscan both reside inside a
Folders and namespaces
Namespaces and the folder structure that contains the
.cs files have a close relationship. To define the correct folder structure helps keeping the relationship with the namespaces. This, in turn enables additional functionalities, such as deriving the web address of the source code of a method.
Enum, and an
Interface, the folder structure respects the following rules:
If a file is in a sub folder, the namespace of the entity must follow: if
Baris in a sub folder
Elements, its namespace must suffix the
Enummust be in a separate folder
Enums. Although, the namespace remains unchanged, and does not follow - i.e.
Enumsis appended as suffix. For example
BarFEATypeis in the sub folder
Elements, and it is an
enum. Its namespace respects A., so it contains the
Elementsword, but does not contain the
Enumword: BH.oM.Structure.Elements. At the same time, since it is an
Enumit is in an
The same rule as B. applies to:
The order an Enum is written is the order in which it is displayed in the UI dropdown options. This order is therefore important to the UX of using the Enum within a workflow. The order should therefore follow one of the following conventions. There may be occasions when an Enum order does not follow the conventions below. These occasions should be clearly documented with the reasons why a different convention has been followed.
The order of the Enum should be alphabetical (following British-English spelling conventions) in ascending order (i.e. A-z).
If your Enum option has an
Undefined option to denote a default unset option, then this should go as the first option at the top of the Enum.
For an example of an Enum following this convention, see the Environment Panel Type Enum.
The order of the Enum can be in a logical order instead where this makes more sense than alphabetical. An example of such an Enum might be one that records the size of an object. In this case, the options might be:
This order for the Enum makes logical sense and provides a good UX where users will have context from the name of the Enum that the order might be different to alphabetical (e.g. the name might be
For conditional statements, the variable expression should be placed in front of the constant expression. When this order is reversed, it is referred to as a "Yoda condition". For readability, we avoid using Yoda conditions in our code base. An example of both is given below.