Nullability Coding Guideline for Properties and Fields

When faced with the option of enabling nullable reference types, we have several choices for reference type based properties.

• Given a non-nullable read-write property, should we A) use a full property implementations with a backing field and setter validation to check for null or B) use automatically implemented properties that doesn't prevent null assignment (communicating non-null intent but allowing null in the implementation)? A
• Given a non-nullable property, should we A) require (in the guidelines) the property be assigned before instantiation is complete or B) allow the default null value to remain after instantiation even though the property intent is non-nullable? A
• Do we enable nullable reference type support for a new project, A) enabling the ability to declare intent on the nullability of our API or B) ignore the feature? A
• Do we A) enable nullable reference type support for a brown field project and then turn it off for all files until warnings can be processed or B) ignore the null reference type feature, C) enable it on a per-file basis as nullability support is added to the file (given #nullable enable/disable pre-compiler directives, we could do this at a sub-file level)? Prefer A or C
• For automatically implemented properties, are we comfortable with a guideline that limits code to only 1) nullable automatically implemented properties or 2) read-only non-nullable instantiation initialized properties? Yes

Based on the above choices, here are the recommended coding standards:

• DO enable nullable on new projects and migrate towards enabling nullable on existing projects.

• DO implement non-nullable read/write reference properties with a nullable backing field, a null forgiveness operator when returning the field from the getter, and non-null validation in the property setter.

• DO assign non-nullable reference type properties before instantiation completes.

• DO use a nullable reference types for all properties and fields that are not initialized before instantiation completes.

• DO implement non-nullable reference-type automatically implemented as read-only.

• DO decorate non-nullable automatically implemented reference type properties the with nullability modifier and the NonNull and DisallowNull attributes if the property values are initialized automatically by an external agent.
  Example:
  [DisallowNull][NotNull]
  public string? Name { get; set; }

This should be compatible with the existing coding standards around properties and fields:

• DO favor automatically implemented properties over properties with simple backing fields when no additional logic is required
• DO favor automatically implemented properties over fields
• AVOID accessing the backing field of a property outside the property, even from within the containing class.
• DO create read-only automatically implemented properties in C# 6.0 (or later) rather than read-only properties with a backing field if the property value should not be changed.

Examples:

1. Employee (possibly a DTO) has nullable automatically implemented properties or non-nullable properties with backing fields to check for null, or a

class Employee
{
    public Employee(string name, string ssn)
    {
        Name = name;
        Ssn = ssn ?? throw new System.ArgumentNullException(nameof(ssn));
    }

	public string? Title {get;set;}
    public string Ssn {get;}
    public string Name
    {
        get => _Name!;
        set => _Name = value ?? throw new System.ArgumentNullException(nameof(value));
    }
    private string? _Name;
}

2. The TestContext property is initialized by an outside agent (MSTest) so it is nullable, but marked as not-null so that no checking is required before dereferencing.

[TestClass]
public class ProgramTests
{
    [System.Diagnostics.CodeAnalysis.NotNull]
    public TestContext? TestContext { get; set; }

    [TestMethod]
    public void Main_AccessingFields_WriteFieldValues()
    {
        Assert.IsNotNull(TestContext);
    }
}