Description
As discussed in #324, we should write up a contribution guideline to make it easier to contribute and review.
Rules that are enforced by test cases are marked with an asterisk *
and #328 will add the initial set of tests.
Updated 2018-02-04 by Andreas:
Coding Conventions
- Match the existing code style, we generally stick to "Visual Studio defaults" and .NET Foundation Coding Guidelines
- If you use ReSharper there is a settings file that will take effect automatically
- There is an .editorconfig to configure whitespace and some C# syntax
- Add the file header to new files you create
Test Code
- Test class: Use
Tests
suffix for the type you are testing, such asUnitSystemTests
- Test method:
<method>_<condition>_<result>
(Parse_AmbiguousUnits_ThrowsException
) - If there are many tests for a single method, you can wrap those in an inner class named the same as the method and then you can skip that part of the test method names
Unit definitions (.JSON)
For a fairly complete summary of the unit definition JSON schema, see Meter of Length. It has prefix units and multiple cultures.
Conversion functions
Converting from unit A to B is achieved by first converting from unit A to the base unit, then from the base unit to unit B. To achieve this, each unit defines two conversion functions.
- Prefer multiplication for
FromUnitToBaseFunc
(x*2.54e-2
forInch
toMeter
) - Prefer division for
FromBaseToUnitFunc
(x/2.54e-2
forMeter
toInch
) - Prefer scientific notation
1e3
and1e-5
instead of1000
and0.00001
- Prefer a constant if the conversion factor is finite (
x*2.54e-2
forInch
) - Prefer a calculation if the conversion factor is infinite (
(x/72.27)*2.54e-2
forPrinterPoint
)
Units
Generally we try to name the units as what is the most widely used.
- Use prefix for country variants, such as
ImperialGallon
andUsGallon
Note: We should really consider switching variant prefix to suffix, since that plays better with kilo, mega etc.. Currently we have units named KilousGallon
and KiloimperialGallon
, these would be better named KilogallonUs
and KilogallonImperial
.
Unit abbreviations
A unit can have multiple abbreviations per culture/language, the first one is used by ToString()
while all of them are used by Parse()
.
- Prefer the most widely used abbreviation in the domain, but try to adapt to our conventions
- Add other popular variants to be able to parse those too, but take care to avoid abbreviation conflicts of units of the same quantity
- Use superscript (
cm²
,m³
) instead ofcm^2
,m^3
- Use
∆
for delta (not▲
) - Use
·
for products (N·m
instead ofNm
,N*m
orN.m
) - Prefer
/
over⁻¹
, such askm/h
andJ/(mol·K)
- Use
h
for hours,min
for minutes ands
for seconds (m
is ambiguous with meters) - Use suffixes to distinguish variants of similar units, such as
gal (U.S.)
vsgal (imp.)
for gallons(U.S.)
for United States(imp.)
for imperial / British units