Essentials: Best Practice Guidelines

[jamesmontemagno]

Enums

• Always use Unknown at index 0
• Follow naming guidelines for tense... SensorSpeed not SensorSpeeds
• Assign values for all enums

Property Names

• Include units only if one of the platforms includes it in their implementation. For instance HeadingMagneticNorth implies degrees on all platforms, but PressureInHectopascals is needed since platforms don't provide a consistent API for this.

Units

• Use the standard units and most well accepted units when possible. For instance Hectopascals are used on UWP/Android and iOS uses Kilopascals so we have chosen Hectopascals.

VS bug #735655

[mattleibow]

This should maybe go into a wiki or the contributing.md

[jamesmontemagno]

Yeah, i want to rev on it here and bring it into the contributing area probably.

[Mrnikbobjeff]

Prefer comparisons using == over is when checking for null, as you mentioned in #616 review

[Mrnikbobjeff]

Another question which might be best answered at a project level: should we prefer default over SampleEnum.Unknown? If all enums are supposed to have Unknown as default value we can use default for brevity.

[Redth]

@Mrnikbobjeff i'm not sure I understand. You want to use Default instead of Unknown? General API guidance from the .NET team has been use Unknown, though sometimes it might make sense to also have a Default.

[Mrnikbobjeff]

@Redth I was not specific enough in my previous post. My question was given an enum SampleEnum {Unknown = 0, Test = 1} and a function f() which returns a SampleEnum value, should/can we use "return default;" instead of explicitely returning SampleEnum.Unkown

[Redth]

In theory yes, but as we were reviewing some code changes for this, we had decided that returning Unknown explicitly was more readable to most people in code.

[Mrnikbobjeff]

I would love to see some guidelines regarding Exceptions. AFAIK we still don't have a common Exception for runtime errors such as discussed in #457 - This might come up in bluetooth and contacts and should generally be clarified so that future PR's can conform to that :)

[mattleibow]

We have a whole issue for that #19 😄

[jamesmontemagno]

This is now in: https://github.com/xamarin/Essentials/pull/692