[Method Contracts] Extensibility of flow state analysis via attributes

[Rekkonnect]

Summary

This proposal enables extending the capabilities and coverage of flow state analysis via attributes onto method contracts.

Motivation

Since the release of C# 8.0, with the introduction of nullable reference types, most JetBrains' flow state analysis attributes were ported over to the BCL with native support from the compiler for the analysis. Ever since, even more attributes were being added, covering even more scenarios. In C# 11.0, nameof for method parameters was primarily motivated due to this use case, to support writing the nameof expression on the compared method parameter.

This however is never reaching a satisfactory coverage rate due to the attributes' lack of customizability. Each new attribute must be considered and individually analyzed on top of a system that acts as a simulation of a method contract system in a very bound scope, mainly concerning nullability.

Proposal

Enable a fundamental grammar for declaring method contracts, that are encodable in metadata. The metadata encoding is not part of this discussion; it will have its own difficulties that are not considered here.

By method contracts, we mean clauses similar to where on generic type and method declarations. Those contracts will declare the state of certain values and the flow analysis system will be able to keep track of that state, providing a flexible solution for showing fewer false warnings.

Currently, the flow state analysis article mentions the following attributes:

• AllowNull
• DisallowNull
• MaybeNull
• NotNull
• MaybeNullWhen
• NotNullWhen
• NotNullIfNotNull
• MemberNotNull
• MemberNotNullWhen
• DoesNotReturn
• DoesNotReturnIf

There are even more proposals for more attributes and further expansion of the current attribute-based system.

Method contracts can cover all the above scopes, and way further due to their reliance on expressions, pattern-based or not. Those expressions are hints to the compiler, code that will never slip onto runtime execution, and will not impose further strain on the runtime memory by having to load such attributes.

Method contracts will have one major difference compared to the attribute-based approach that is being currently followed, and that is the fact that violation of the declared contracts will result in a compilation error. This is a healthy design in the scope of having compile-time safety without silently leaking a potential bug, or an unwanted exception being thrown. Consumers will have to wisely apply those rules.

Namely, this is how the above attributes will be covered using method contracts:

Examples

All the showcased examples come from the flow state analysis article linked above.

AllowNull

Attributes:

[AllowNull]
public string ScreenName
{
    get => _screenName;
    set => _screenName = value ?? GenerateRandomScreenName();
}
private string _screenName = GenerateRandomScreenName();

Method contracts:

public string ScreenName
{
    get => _screenName;
    set
        allows null value // This allows the parameter value to be nullable
        => _screenName = value ?? GenerateRandomScreenName();
}
private string _screenName = GenerateRandomScreenName();

DisallowNull

Attributes:

[DisallowNull]
public string? ReviewComment
{
    get => _comment;
    set => _comment = value ?? throw new ArgumentNullException(nameof(value), "Cannot set to null");
}
string? _comment;

Method contracts:

public string? ReviewComment
{
    get => _comment;
    set
        // This requires that the value passed onto the property is not null
        // Violation of this contract will result in a compile-time error, as mentioned above
        requires value is not null 
        => _comment = value ?? throw new ArgumentNullException(nameof(value), "Cannot set to null");
}
string? _comment;

MaybeNull

Attributes:

[return: MaybeNull]
public T Find<T>(IEnumerable<T> sequence, Func<T, bool> predicate)

Method contracts:

public T Find<T>(IEnumerable<T> sequence, Func<T, bool> predicate)
    allows null return
// `return` here refers to the returned value

NotNull

Attributes:

public static void ThrowWhenNull([NotNull] object? value, string valueExpression = "")
{
    _ = value ?? throw new ArgumentNullException(nameof(value), valueExpression);
    // other logic elided

Method contracts:

public static void ThrowWhenNull(object? value, string valueExpression = "")
    requires value is not null
{
    // Now we don't have to include the exception to be thrown
    // Older versions of the compiler would refuse to compile against an assembly with method contracts
    // Because of the invalid metadata declarations
    // Therefore, it is not possible to consume assemblies with method contracts without having 
    // higher version of the compiler
    
    // other logic elided

MaybeNullWhen

The original article does not provide an example for MaybeNullWhen, so it was omitted here.

NotNullWhen

Attributes:

bool IsNullOrEmpty([NotNullWhen(false)] string? value)

Method contracts:

bool IsNullOrEmpty(string? value)
    ensures value is not null when return is false
// The ensures clause declares that, upon the method is exited, a condition is met
// with the given conditions, in this instance when the return value equals false

NotNullIfNotNull

Attributes:

[return: NotNullIfNotNull(nameof(url))]
string? GetTopLevelDomainFromFullUrl(string? url)

Method contracts:

string? GetTopLevelDomainFromFullUrl(string? url)
    ensures return is not null when url is not null

MemberNotNull

Attributes:

public class Container
{
    private string _uniqueIdentifier; // must be initialized.
    private string? _optionalMessage;

    public Container()
    {
        Helper();
    }

    public Container(string message)
    {
        Helper();
        _optionalMessage = message;
    }

    [MemberNotNull(nameof(_uniqueIdentifier))]
    private void Helper()
    {
        _uniqueIdentifier = DateTime.Now.Ticks.ToString();
    }
}

Method contracts:

public class Container
{
    private string _uniqueIdentifier; // must be initialized.
    private string? _optionalMessage;

    public Container()
    {
        Helper();
    }

    public Container(string message)
    {
        Helper();
        _optionalMessage = message;
    }

    private void Helper()
        ensures _uniqueIdentifier is not null
    {
        _uniqueIdentifier = DateTime.Now.Ticks.ToString();
    }
}

MaybeNullWhen

The original article does not provide an example for MemberNotNullWhen, so it was omitted here.

DoesNotReturn

Attributes:

[DoesNotReturn]
private void FailFast()
{
    throw new InvalidOperationException();
}

public void SetState(object containedField)
{
    if (containedField is null)
    {
        FailFast();
    }

    // containedField can't be null:
    _field = containedField;
}

Method contracts:

private void FailFast()
    throws always
{
    throw new InvalidOperationException();
}

public void SetState(object containedField)
{
    if (containedField is null)
    {
        FailFast();
    }

    // containedField can't be null:
    _field = containedField;
}

NOTE: There also exist other proposals for handling the case of methods that always throw, like the proposal about the never type to indicate that.

DoesNotReturnIf

Attributes:

private void FailFastIf([DoesNotReturnIf(true)] bool isNull)
{
    if (isNull)
    {
        throw new InvalidOperationException();
    }
}

public void SetFieldState(object? containedField)
{
    FailFastIf(containedField == null);
    // No warning: containedField can't be null here:
    _field = containedField;
}

Method contracts:

private void FailFastIf(bool isNull)
    throws when isNull is true
    // 'throws when isNull' is not designed to be legal, to avoid inference of the value of the parameter
    // It could be allowed in a future revision
{
    if (isNull)
    {
        throw new InvalidOperationException();
    }
}

public void SetFieldState(object? containedField)
{
    FailFastIf(containedField == null);
    // No warning: containedField can't be null here:
    _field = containedField;
}

---

Additional proposals that also introduce more attributes:

MemberNotNullWhenComplete (#5657)

Attributes:

private Potato? _potato;

[MemberNotNullWhenComplete(nameof(_potato))]
private async Task FetchPotatoAsync()
{
    await Task.Delay(100); // Member '_potato' must have a non-null value when exiting.
    await Task.Delay(100); // Member '_potato' must have a non-null value when exiting.
    _potato = new Potato();
}

Method contracts:

private Potato? _potato;

private async Task FetchPotatoAsync()
    ensures _potato is not null when complete
    // Alternatively:
    // ensures _potato is not null when result.IsCompleted
{
    await Task.Delay(100); // Member '_potato' must have a non-null value when exiting.
    await Task.Delay(100); // Member '_potato' must have a non-null value when exiting.
    _potato = new Potato();
}

Risks

• A new system will be required for implementation in the compiler, and a new section is being added onto the metadata of each method and property. Without subjecting anything to breaking changes, this is going to take time and effort, with careful design.
• Many users might not like the idea of having a system that produces compile-time errors. There are many pieces of code using attribute-based flow state analysis from previous versions that will break many users if they switch over to method contracts.
• The method contracts system is generally verbose in nature, requiring that the user explicitly declares properties of the state within the specified scope. To combat that, a code refactoring could be implemented that automatically declares method contracts on the selected property or method.

Extras

All code that relies on the traditional flow analysis system via attributes will be offered a code fix to immediately convert all those attributes into method contracts. This will have to be used wisely, as there is the aforementioned risk of breaking users when updating to a newer version of the assembly that introduces method contracts.

[HaloFour]

That seems like an incredibly complicated syntax to describe the behavior of nullable flow control, and in the end it's all going to have to be boiled down into attributes that can be attached to the methods anyway. This would require a lot of specification work and compiler work just to return to par, and supporting new scenarios is going to end up requiring new flavors of this DSL and the metadata to go along with it.

I also don't understand trying to conflate method contracts with NRT flow analysis. I would expect that method contracts would affect the runtime semantics of the method, where flow analysis certainly shouldn't.

[Rekkonnect]

NRT flow analysis was introduced exactly to help guide the nullability state of the code, but could not introduce runtime semantics because of the fact that reference types are nullable from day one. The motivation was initially to prevent bugs from slipping their way into the runtime in the form of null ref exceptions, because of some oversight from the programmer.

Method contracts introduce runtime semantics by not ever reaching the runtime without properly ensuring that some preconditions are met. This is the healthier approach, as I've already mentioned in the proposal itself, by guaranteeing and proving that there is no chance that a null reference is ever reached.

Method contracts do not alter state, by definition. Their purpose is exactly to prove that a described state is present and that it is never violated, within the method or outside.

[HaloFour]

Method contracts already have a championed proposal here: #105

[Rekkonnect]

I know, and I've already upvoted it. This proposal is solely for the purpose of migrating from attribute-based static analysis to being based on method contracts.

[HaloFour]

If method contracts were to become a thing I don't think they would replace the flow analysis for NRTs given the intentional design choice to not have any runtime impact. They would have some overlap, but the policy for violation would be a very different beast.