Style Guide and GitHub Good Practice

This page provides a check list that should be used when contributing a new class (model, block, function etc.) to the library.

General

Follow the conventions in Annex60.UsersGuide.Conventions. (This link will be replaced with a link to the Annex library when the first html version is posted.)
Partial classes and base classes that are not of interest to the user should be stored in a subdirectory called BaseClasses.
Do not copy sections of code. Use object inheritance.
Implement new components of building component, fluid flow and electric systems by extending from the partial classes in the respective Interfaces directories.
Use the full package names when instantiating a class.

For every branch, an issue has to be made denoting what problem is addressed (or vice versa). The issue has to has a clear title (e.g. Changing X in Y for reason Z), and the resulting issue number has to be used to name the branch `issue#_XinY`.
A single exception on this is the `develop`-branch, which is used as a basis for development for all branches as the future `master`-branch.
The `OpenIdeas` GitHub repository is only used for debugging and IEA EBC Annex 60 developments. Any developments of entirely new models should be made on a fork of the repo to a personal git repo, fully developed and tested there, and requested for integration in `OpenIdeas` with a pull-request.
Before making a github pull-request of the `compare`-branch to the `base`-branch, always first do an opposite pull-and-merge of the desired `base`-branch to the `compare`-branch to have a conflict-free pull request to be reviewed by a third person.
Use GitHub Flavored Markdown in all issue discussion or in the wiki.

Declare variables and final parameters that are not of interest to users as protected.
Set default parameter values as follows:
1. If a parameter value can range over a large region, do not provide a default value.
2. If a parameter value does not vary significantly, provide a default by using its start attribute, e.g. use
```
parameter Real eps(start=0.8, min=0, max=1, unit="1") "Heat exchanger effectiveness";
```
3. If a parameter value can be precomputed based on other parameters, set its default value to this equation, e.g.
```
parameter Medium.MassFlowRate mFloSmall(min=0) = 1E-4*mFloNom;
```
4. If a parameter value should not be changed by a user, use the final keyword.
For any variable or parameter that may need to be solved numerically, provide a value for the start and nominal attribute.
Use types from Modelica.SIunits where possible.

Avoid events where possible.
Only divide by quantities that cannot take on zero.
Use SI units in all equations.
Use the assert function to check for invalid values of parameters or variables.
Use either graphical modeling or textual code. Avoid using both within one class.
For computational efficiency, equations shall were possible be differentiable and have a continuous first derivative.
Avoid equations where the first derivative with respect to another variable is zero, except at a single point.
Do not replace an equation by a constant for a single value, unless the derivative of the original equation is zero for this value.
Whenever possible, a Modelica tool should not have to do numerical differentiation. For example, in Dymola, if your model translation log shows Number of numerical Jacobians: 1 (or any number other than zero), then enter on the command line Hidden.PrintFailureToDifferentiate = true; Next, translate the model again to see what functions cannot be differentiated symbolically. Then, implement symbolic derivatives for this function. See implementation of function derivatives.

Class and instance names are written in CamelCase (upper and lower case letters), e.g., ElectricCurrent. An underscore is only used at the end of a name to characterize a lower or upper index, e.g., pin_a.
Class names start always with an upper case letter.
Instance names, i.e., names of component instances and of variables (with the exception of constants), start usually with a lower case letter with only a few exceptions if this is common sense (such as T for a temperature variable). See the table below for examples and exceptions.
Constant names, i.e., names of variables declared with the "constant" prefix, follow the usual naming conventions (= upper and lower case letters) and start usually with an upper case letter, e.g., UniformGravity, SteadyState.
The two connectors of a domain that have identical declarations and different icons are usually distinguished by _a, _b or _p, _n. Examples: Flange_a, Flange_b or HeatPort_a, HeatPort_b.

These rules are additions to the basic rules above:

Variable names start with the symbol. Example: TSet, T_start, pOut, mFlow_nom (and NOT setTemperature or outletPressure or NomMFlow or something like that)
If possible and clear, abbreviate sequences to 3 letters for instances. For long words this is strongly encouraged, for short (4 and 5 letter words) this is not necessary, although it is possible. Class names do not have to be abbreviated.
Each package starts with import SI = Modelica.SIunits; All variables should be instances of this package. Examples: SI.Temperature or SI.MassFlowRate.
The Modelica sign convention denotes: flow INTO component is POSITIVE (for mass flow rates, current, etc.) You can remember this by a simple rule: modelica components are egoistic: getting something is positive for them. This means for electric power: a positive power at a connection => the object consumes electricity.
Efficiencies and ratios: no unit, no percentage (1 instead of 100%, also called “base 1”)

Add a one-line comment to all parameters and variables, including protected ones.
Provided a detaield explanation of the implemented physics in the Specifications section in LaTeX.
Group similar variables using the group and tab annotation.
Add model documentation to the info section.
Add author information to the revision section.
Run a spell check.
For complex packages, provide a User's Guide, and reference the User's Guide in Buildings.UsersGuide.