> For the complete documentation index, see [llms.txt](https://dev.open-systems-pharmacology.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.open-systems-pharmacology.org/setup/coding_standards.md).

# C# Coding Standards

## Visual Studio Settings

* Use indentation of 3.
* Use spaces instead of tabs.
* If using Resharper, make sure a Resharper settings file is available to format your code.

## Naming Convention

Use meaningful and understandable names. Code should read as a story and only some well known abbreviations such as DTO, PK etc. should be used.

### Classes and Methods

* Use **Pascal Casing** for class name `public class SomeClass`.
* Use **Pascal Casing** for public and protected method name `public void SomeMethod()`.
* Use **Camel Casing** for private method name `private int somePrivateMethod()`.
* Prefix interface with I `public interface IMyInterface`.
* Suffix exception classes with Exception `public class SBSuiteException: Exception`.

### Variables

* Prefix private/protected member variable with `_` (underscore): `private int _parentContainerId`.
* Use **ALL\_CAPS Casing** for constant variables: `public const double DEFAULT_PERCENTILE = 0.5;`.
* Use **Camel Casing** for local variable names and method arguments: `int ingredientNode`.
* All members variable should be declared at one place of a class definition.
* Prefer variables initialization at the point of declaration .
* Do not use public members. Use properties instead.
* Do not use Hungarian notation (e.g. b for boolean, s for strings etc.).
* Except for program constants, never use global variables.

### Comments

* Do not comment the obvious
* Indent comment at the same level of indentation as the code you are documenting
* All comments must be written in English
* Do not generate comments automatically
* Do comment algorithm specifics. For example, why your loop starts at index 1 and not at 0.
* If a lot of comments are required to make a method easier to understand, break down the method in smaller methods
* Really, do not comment the obvious

## Coding Style

* No hard coded strings and magic number should be used. Declare a constant instead.
* Method with return values should not have side effects unless absolutely required.
* Exit early instead of having nested if statements.

  For example, instead of

  ```
  public void UpdateValue(bool isVisible, bool isEditable, double value)
  {
    if(isVisible)
    {
      if(isEditable)
      {
        _value = value;
      }
    }
  }
  ```

  use

  ```
  public void UpdateValue(bool isVisible, bool isEditable, double value)
  {
    if(!isVisible || !isEditable)
      return;

    _value = value;
  }
  ```
* Do not write `if` statements in one line.
* Do not write `for` and `forEach` statements in one line.
* Always use block `{}` for `for` and `forEach` statements.
* Always have a default case for `switch` statement, potentially throwing an exception if the default is unreachable.

## **Best Practices**

### DOs

* Use IReadOnlyList/IReadOnlyCollection as return type or parameter of your public APIs instead of IEnumerable.
* Create methods such as *Add*, *Remove* in your class if you need to modify an internal list instead of exposing the list to the outside world.

### DON'Ts

* Do not use IList/List as a return type or parameter of public APIs (methods or class member). By using those, you are breaking encapsulation and anyone can modify the list which makes debugging very hard.
* Do not use ICache/IDictionary as return type or parameter of public APIs. By doing so, you are duplicating the knowledge of how the key is constructed. This is also a break in encapsulation. Create your own class derived from Cache if you need to use a Cache construct as part of API.