Proposal: Guard statement in C#

[Eyas]

Background

Swift has a guard statement that can be very valuable in writing code that is easy to reason about. See Swift Guard Statement - why you should use it.

Problem

If we have a function Foo that takes an integer that must be positive (> 0), we can write that as:

Bar Foo_alt1(int b) {
    if (b > 0) {
        // all of our code is surrounded by checks for the condition.
        // special handling of condition is far away from the statement of what the condition is
        // extra indent, extra nesting, etc.
    } else {
        throw new IllegalArgumentException(nameof(b));
    }
}

Bar Foo_alt2(int b) {
    // 'syntactic sugar' disadvantage is that now we check for the "negative"
    // condition instead of the positive. this might be natural in cases of null checking or
    // other simple checks, but can become burdensome in complex cases of many comparisons
    // and logical operators.
    if (b <= 0) {
        throw new IllegalArgumentException(nameof(b));
    } else {
        // rest of code to handle the normal case is here.
        // 'excessive' nesting and indentation
        return foo;
    }
}

Bar Foo_alt3(int b) {
    // 'syntactic sugar' disadvantage is that now we check for the "negative"
    // condition instead of the positive. this might be natural in cases of null checking or
    // other simple checks, but can become burdensome in complex cases of many comparisons
    // and logical operators.
    if (b <= 0) {
        throw new IllegalArgumentException(nameof(b));
    }

    // rest of code to handle the normal case is here.
    // we choose not to resort to nesting, but in doing so, we lose an important compile-time check:
    // a programmer error might result in the if-block above not returning or throwing, thus
    // causing the control flow to drop off into the "normal" code
    return foo;
}

Proposed Solution: guard statements

Bar Foo(int b) {
    // state that b must be a positive integer
    guard (b > 0) else {
        throw new IllegalArgumentException(nameof(b));
    }
    // compiler verifies that the guard-block throws or returns, thus
    // guaranteeing that code here will satisfy the guard condition.
    // ... do something with b without worrying about edge cases
}

Benefits

The guard statement introduces two benefits over if-based guards:

1. Syntactic sugar of declaring the positive condition we would like to meet after the guard, rather than the negatives
2. Compile-time checking of the fact that the guard clause ends control flow by returning or throwing
3. One less indent :)

Grammar

guard-statement
    : 'guard' ( boolean-expression ) 'else' embedded-statement
    ;

[alrz]

Also check out #119 and #6400.

[Eyas]

@alrz right. unless is what its called in Ruby, Swift is calling it guard. I prefer guard because it relates to the guard refactoring pattern.

While I like contract I think this is quite different from #119: the guard block could result in an exception thrown for an invalid argument, but could also include non-errored handling of edge cases. E.g.:

int fib(int n) {
    guard (n > 1) else return 1;
    return fib(n - 1) + fib(n - 2);
}

The else clause in #6400 is very close to what we want, but:

1. We want to check on boolean-expression rather than pattern.
2. The conditions we check for can span multiple variables and assignments, e.g.:

void Configure(Configuration c) {
    guard (URLExists(c.URL) or FileExists(c.File)) else {
        Console.WriteLine("Supplied configuration does not contain a valid file or URL.");
        return;
    }
    // ...
}

[mburbea]

And what's wrong with

if (!(b > 0)){
      throw new InvalidArgumentException(...)
}

It handles your case. I don't find that unless or guard Adds a lot of value to the language. It adds another way to do the exact same thing, and then developers will have to learn new syntax, and have another form to worry about when reading code.

[Eyas]

@mburbea This is what I explained in the "Problem" section, the main issue with the if (!(...)) { is that the compiler doesn't guarantee that the embedded statement after the if-guard terminates. So I can do something like:

if (b == null) {
   // print a complicated error
   // forget to return or throw
}

foo = b.bar(); // <-- control drops here in the b is null case and we get an error

So yes, benefits are:

1. Checking for the positive condition (guard (b > 0) else ...) is "pretty" syntactic sugar
2. Compiler verifies that the else clause will terminate, so that code after the guard clause provably runs only when the guard conditions are true.

[HaloFour]

@Eyas

#6400 does handle that, else must throw or return.

Otherwise I don't see anything particularly wrong with it but I'm not sure that it's particularly necessary. I want to dislike it more just because Swift has it, but meh.

[HaloFour]

I will say that the one reason that I dislike this and #119 is that it doesn't offer any proposal for metadata attached to the method to declare such constraints. Handling illegal arguments is one thing, preventing them from happening is significantly more.

[Eyas]

@HaloFour See my examples in the comment above:

1. the guard clause does not constrain parameters or variables passed, but rather provides a guarantee on these variables after the statement. The else clause can simply return (see fib example). This is valuable as-is, and is orthogonal to annotating the "type" of a function or scope.
   • I dislike Proposal: Method Contracts #119 because it actually defines valid and invalid parameters yet doesn't annotate their types appropriately.
   • Unlike Proposal: Method Contracts #119, this doesn't define legal and illegal cases. And so doesn't interact with type/metadata
2. the guard clause is different than let in that:
   • the condition is a boolean expression, not a pattern
   • the condition could be a global thing, or an and of multiple values, or a more complex condition, rather than a condition related to a single variable or assignment. See the Configure example.

[HaloFour]

@Eyas You're right. I think after the defer proposal I was looking for a fight. 😉

[Richiban]

I still think that the requirements this proposal seeks to address would be supported by pattern matching -- I think it would even look fairly similar. Consider this pseudocode:

public int F(int? arg)
{
    match (arg)
    {
        null | x when x < 0 =>
        {
            throw new ArgumentException("arg cannot be null or negative");
        }
        i =>
        {
            // Do something with variable 'i' which is now a regular int
        }
    }
}

You get all the requested features above:

• the guard appears first in the method
• the body of the guard must return or throw
• you get the opportunity to match on the variable given your guards passed
• it is possible to match on anything, not just the parameters of your method