Proposal: Guard statement

[scottdorman]

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
    ;

See Also

• Proposal: Guard statement in C# roslyn#8181
• Proposal: Method Contracts roslyn#119
• Proposal: Destructuring (assignment?) statement roslyn#6400
• Proposal: guard statement roslyn#11562

[gulshan]

Method contracts #105 is trying to solve the same problem.

[Thaina]

@gulshan The purpose of guard statement is covered more than just parameter. It can be used on variable later on

[Thaina]

I would still go against adding guard keyword. I suggest return if syntax

dotnet/roslyn#11562 (comment)

void Guard(string s)
{
    return if(!int.TryParse(s, out var value))
    {
        // handle or report the problem
        // auto return after this block
    }

    // use value
}

[gulshan]

@Thaina Isn't return if(..) very similar to already supported if(..) return or if(..) throw? The case for guard is to check with the positive condition- guard(int.TryParse(s, out var value)), not with the negative condition like if return or return if.

[Joe4evr]

You've already linked dotnet/roslyn#11562 which was on the table for the LDM team before they decided to make out var declarations leak into the enclosing scope instead of introducing the (potentially) confusing guard statement. The odds of them turning around on this decision is extremely unlikely because there is already a lot of code relying on the leaky behavior, and you know how much the language team holds to making sure valid code today is valid code forever.

[Thaina]

@gulshan Not quite

What return if do is, it explicitly show from the first line of block that the whole block will surely return for meeting that condition. It just scoped syntax to help code more obvious

I would compare it to using for dispose. It making scope to ensure that it will dispose for that block so you will never forget to add dispose after you use it. In the same manner, guard or return if doing the same thing, ensure that this if block will not go below if it met the condition

To put it simply. We may have code like this

void DoSomething()
{
    if(condition)
    {
        // 20 lines of code
    }
    else
    {
        // 40 lines of code
    }
}

We might try to make less indent

void DoSomething()
{
    if(condition)
    {
        // 20 lines of code

        return;
    }

    // 40 lines of code
}

But it will not so obvious. It will be a bug if we forget to add return in the last

void DoSomething()
{
    return if(condition) // Much more obvious
    {
        // 20 lines of code
    }

    // 40 lines of code
}

[gulshan]

@Thaina return if is still checking with negative condition, not the positive one like guard.
And I think, if there's 20 lines of code when the parameters are not valid, then the code should be restructured and this code is not a good candidate for using guard statement.

[Thaina]

@gulshan Indeed it opposite check

But this is just minor
If we use guard we might write guard(obj != null)
If we use return if we might write return if(obj == null)

Not difference. I just don't like adding new keyword while we can reuse keyword we have. return if not break existing code anyway

[Thaina]

@gulshan And it not only about "the parameters are not valid" there could be any kind of logic with condition that if it meet some condition it will do one branch of logic and return

void DoSomething()
{
    return if(condition0)
    {
        // 8 lines of code
    }

    return if(condition1)
    {
        // 8 lines of code
    }

    return if(condition2)
    {
        // 8 lines of code
    }

    // 12 lines of code for not met any condition above
}

[michaelcheers]

I don't see how

guard (b > 0) else throw new IllegalArgumentException(nameof(b));

is any better than

if (b <= 0) throw new IllegalArgumentException(nameof(b));

I suppose it could be easier to read and an automatic negation but I don't think that's a big enough reason to add a feature to C#.

[soraphis]

Same here. "guard ... else" is imho the same as 'if .... else':

if (b > 0) {} else throw new IllegalArgumentException(nameof(b));

[Thaina]

@michaelcfanning Having keyword like guard have benefit to constraint error in compile time

As I was state above. This feature could compare to using that it really done nothing. You could dispose object manually

But using make a block to ensure that you will not forget to dispose. And also make it explicitly safe that outside this block cannot use that variable, because it already disposed

Same reason when you have a code block that branching off. To ensure that when condition don't match it will not touch a block of code below if block. guard statement could protect you

[iam3yal]

match is going to be an expression so depends on the design the following might be possible in the future:

void DoSomething()
{
    return match(...)
    {
        // ...
    }
}

[lachbaer]

It looks to me as if guard would be only syntactic sugar

guard (b > 0) else throw new IllegalArgumentException(nameof(b));

instead of

if (!( b > 0 )) throw new IllegalArgumentException(nameof(b));

And I don't like return if statements, because it partly obfuscates where and maybe whether in a middle of a function you're gonna return.

And just by looking at it I don't really get what

    return if(condition0)
    {
        // 8 lines of code
    }

will mean. return if condition is met, or is not met? When will the block be executed. Will it be executed when the condition is met and after that the function will be left?

As long as it is not kind of intuitive, these constructs should not be allowed!

[iam3yal]

I'm not sure why it needs to be guard (b > 0) else { } instead of just guard (b > 0) { }.

[lachbaer]

@eyalsk
Because otherwise it would read like "guard if (b > 0) and if it is so process the block", instead of "guard if (b>0) but if not then execute the block".

[orthoxerox]

IIRC, the idea behind the original guard statement was to leak variables into the outer scope and ensure that something bottom-typed like return or throw or FailFast is evaluated otherwise. Now that regular ifs leak variables into the outer scope I don't see how Assert<ArgumentNullException>(b <= 0, $"{nameof(b)} must be a positive integer"); is any worse than adding guard.

[HaloFour]

Without the explicit scope leakage benefits there is little reason to implement guard in C#. Sure, the enforcement of exiting the current block is useful, but I don't believe that it's worth the price of admission.

@orthoxerox

I will say that the Assert helper that you've demonstrates is worse in one significant way; it evaluates that expression to build the exception message whether or not the test failed. If you had concatenated the message in your example that wouldn't be an issue as the compiler would be smart enough to optimize that away, but you used String interpolation which isn't the lightest-weight of invocations. I'd recommend deferring that evaluation via Func<string> or similar.

[MovGP0]

Code Contracts (#105) seems to be the better idea. No need to reinvent the squared wheel.

[iam3yal]

@MovGP0 I really hope this will get implemented at some point. :)

[Thaina]

@MovGP0 I think it's not the point of this feature. Code Contract is not compile time

[iam3yal]

@Thaina If #105 will get implemented then it will be part of the language and may or may not be done at compile-time depends on the design.

[MovGP0]

@Thaina To my knowledge, Code Contracts are enforced by the CLR since v4.0 (ca. 2008) at runtime. Violations cause an exception in the calling code.

[Thaina]

@MovGP0 I think so that's why it not related to guard syntax. guard syntax main purpose is to block usage of variable at compile time

[iam3yal]

@Thaina But it might get implemented as part of the language... and then the guard construct would be useless.

[gulshan]

Note: Method contracts will probably not cover pattern matching.

[Pzixel]

Code contracts should cover this.

[OmidID]

Guard has another idea. You will lock the local variable not an inveted if !!!!

public MyViewModel ViewModel { get; set; }

public async Task DoSomethingAsync()
{
   if (ViewModel == null) return;

   // Start Long Task
   await Task.Delay(5000);

   // ViewModel possible get null here
   await ViewModel.DoSomethingElseAsync();
}

...

public void Dispose()
{
   ViewModel = null;
}

How guard will protect your variable here:

public MyViewModel ViewModel { get; set; }

public async Task DoSomethingAsync()
{
   guard (var vm = ViewModel) else {
      return;
   }

   // Start Long Task
   await Task.Delay(5000);

   // vm is not null for sure
   await vm.DoSomethingElseAsync();
}

[Flutterish]

unless? I have trouble reading the guard syntax, it sounds weird.

[snow-jallen]

The way elixir handles this is oh so slick, and C# could do something quite similar without new keywords or anything too confusing, you just pattern match off of the function header.

public int DoThing(int x) when x < 2
{
  Console.WriteLine("I do this when x is small");
}

public int DoThing(int x) when x < 10
{
  Console.WriteLine("I do this when x is medium");
}

public int DoThing(int x)
{
  Console.WriteLine("I do this when x is big");
}

Sooo much cleaner than statements within the method - it makes it blatantly obvious when each method is called and you can guarantee that within that method x will be validated on whatever rules are necessary.

C# 9 gets us kinda sorta close, but it's still nothing near as slick as the above example.

        public static int HandleNum(int x) => x switch
        {
            < 2 => handleSmallNum(x),
            < 10 => handleMediumNum(x),
            _ => handleBigNum(x)
        };

        private static int handleSmallNum(int x)
        {
            return x;
        }

        private static int handleMediumNum(int x)
        {
            return x;
        }

        private static int handleBigNum(int x)
        {
            return x;
        }

[HaloFour]

See: #4182

TL;DR: Unlike functional languages, in C# overload resolution is handled at compile-time, not at runtime. Failure to resolve would end up being a runtime exception, not a compiler error. The lexical ordering of the member declarations is also not important in C#, but it becomes critically important in this model due to having to establish a priority for the patterns.

[danfma]

That's a good point but IMHO I don't see the possibility of generating runtime-only errors as a problem.
It will be just syntactic sugar for common error-handling scenarios.

public int DoThing(int x) when x < 2
{
  Console.WriteLine("I do this when x is small");
}

Above, could be translated to:

public int DoThing(int x)
{
  Contract.Requires(x < 2, nameof(x), "No satisfies 'x < 2' constraint");
  Console.WriteLine("I do this when x is small");
}

However, I know this is an old topic because it is just the contracts history coming back again.

[marchy]

'Guard Let' Consideration

This proposal and discussion missed out on what is one of the most fundamental and valuable uses of Swift's guard statement, and that is the guard let part.

In addition to inverting the 'if' check, the if let / guard let keywords ALSO check for nullability, and in guard's case allows code below the statement to not need to take on another level of nesting if the condition fails. This mix of declaration pattern and forced code block exit (ie: return/continue) give it unique abilities that you CANNOT practically achieve without it, it is the realm of compilers to generate such code consistently and with the right error semantics always in place.

Given:

record SomeObject (string? someProperty);

Currently (without pattern-matching):

if( someObject.SomeProperty is null )
	return; // or 'continue'
string someProperty = someObject.SomeProperty;

// use 'someProperty', guaranteed to not be null
...
... 
...

Currently (with pattern-matching):

if( someObject.SomeProperty is string null ){
	// use 'someProperty', guaranteed to not be null
	...
	...
	...
} else {
	return; // or 'continue'
}

With 'guard let':

guard (someObject.SomeProperty is string someProperty ) else return; // or 'continue';

// use 'someProperty', guaranteed to not be null
...
...
...

**With current pattern

While we could hack around this with the current Null Checks pattern matching, the main point is that the inverse declaration pattern is not currently supported and does not allow for the same semantics to be achieved.

[svick]

You can use the not pattern for this:

if (someObject.SomeProperty is not string someProperty)
{
    return; // or 'continue'
}

// use 'someProperty', guaranteed to not be null

[marchy]

@svick You just made my day!

I've submitted a request to update the documentation to showcase this extremely useful scenario.

Modern, null-safe, idiomatic C# for the win!! 🎉

[OFark]

or return if(someObject.SomeProperty is not string someProperty)