What value is returned when a method exits early on a return keyword with no argument?

Question

Consider the following Ruby method:

def increment(value)
    return if value >= 999
    
    value + 1
end

What value gets returned to the caller from this method if the return statement executes?

From running this code myself, it appears that nil is returned. But is it always guaranteed to be the case that a return with no argument specified implicitly returns nil? Is this behavior documented somewhere? Is the behavior Ruby language version-dependent?

I checked several of the various sites linked to from https://www.ruby-lang.org/en/documentation/, including http://www.ruby-doc.org/docs/ProgrammingRuby/, without locating a definitive answer.

Answer 1

return is a Ruby keyword. From the documentation:

return Exits a method. See methods. If met in top-level scope, immediately stops interpretation of the current file.

From the return values section of the methods documentation:

By default, a method returns the last expression that was evaluated in the body of the method. ... The return keyword can be used to make it explicit that a method returns a value.

From The Ruby Programming Language by David Flanagan and Yukihiro Matsumoto (creator of the Ruby programming language), chapter 5.5.1 return:

return may optionally be followed by an expression, or a comma-separated list of expressions. If there is no expression, then the return value of the method is nil. If there is one expression, then the value of that expression becomes the return value of the method. If there is more than one expression after the return keyword, then the return value of the method is an array containing the values of those expressions.

This last passage can be considered the canonical answer, though I believe there may be additional information in ISO/IEC 30170 on this.

To clarify how using if as a modifier is evaluated by the interpreter in your example, I'll again quote The Ruby Programming Language, chapter 5.1.2 if As a Modifier:

When if is used in its normal statement form, Ruby’s grammar requires that it be terminated with the end keyword. For simple, single-line conditionals, this is somewhat awkward. This is just a parsing problem, and the solution is to use the if keyword itself as the delimiter that separates the code to be executed from the conditional expression. Instead of writing:

if expression then code end

we can simply write:

code if expression

When used in this form, if is known as a statement (or expression) modifier. If you’re a Perl programmer, you may be accustomed to this syntax. If not, please note that the code to execute comes first, and the expression follows. For example:

puts message if message # Output message, if it is defined

This syntax places more emphasis on the code to be executed, and less emphasis on the condition under which it will be executed. Using this syntax can make your code more readable when the condition is a trivial one or when the condition is almost always true.

Even though the condition is written last, it is evaluated first. If it evaluates to anything other than false or nil, then the code is evaluated, and its value is used as the return value of the modified expression. Otherwise, the code is not executed, and the return value of the modified expression is nil. Obviously, this syntax does not allow any kind of else clause.