.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Perl::Critic::Policy::Subroutines::RequireFinalReturn 3pm"
.TH Perl::Critic::Policy::Subroutines::RequireFinalReturn 3pm 2023-07-26 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Perl::Critic::Policy::Subroutines::RequireFinalReturn \- End every path through a subroutine with an explicit "return" statement.
.SH AFFILIATION
.IX Header "AFFILIATION"
This Policy is part of the core Perl::Critic
distribution.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Require all subroutines to terminate explicitly with one of the
following: \f(CW\*(C`return\*(C'\fR, \f(CW\*(C`carp\*(C'\fR, \f(CW\*(C`croak\*(C'\fR, \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, \f(CW\*(C`exit\*(C'\fR,
\&\f(CW\*(C`goto\*(C'\fR, or \f(CW\*(C`throw\*(C'\fR.
.PP
Subroutines without explicit return statements at their ends can be
confusing.  It can be challenging to deduce what the return value will
be.
.PP
Furthermore, if the programmer did not mean for there to be a
significant return value, and omits a return statement, some of the
subroutine's inner data can leak to the outside.  Consider this case:
.PP
.Vb 10
\&    package Password;
\&    # every time the user guesses the password wrong, its value
\&    # is rotated by one character
\&    my $password;
\&    sub set_password {
\&        $password = shift;
\&    }
\&    sub check_password {
\&        my $guess = shift;
\&        if ($guess eq $password) {
\&            unlock_secrets();
\&        } else {
\&            $password = (substr $password, 1).(substr $password, 0, 1);
\&        }
\&    }
\&    1;
.Ve
.PP
In this case, the last statement in \fBcheck_password()\fR is the
assignment.  The result of that assignment is the implicit return
value, so a wrong guess returns the right password!  Adding a
\&\f(CW\*(C`return;\*(C'\fR at the end of that subroutine solves the problem.
.PP
The only exception allowed is an empty subroutine.
.PP
Be careful when fixing problems identified by this Policy; don't
blindly put a \f(CW\*(C`return;\*(C'\fR statement at the end of every subroutine.
.SH CONFIGURATION
.IX Header "CONFIGURATION"
If you've created your own terminal functions that behave like \f(CW\*(C`die\*(C'\fR
or \f(CW\*(C`exit\*(C'\fR, then you can configure Perl::Critic to recognize those
functions as well.  Just put something like this in your
\&\fI.perlcriticrc\fR:
.PP
.Vb 2
\&    [Subroutines::RequireFinalReturn]
\&    terminal_funcs = quit abort bailout
.Ve
.PP
If you've created your own terminal methods, then you can configure
Perl::Critic to recognize those methods as well, but the class won't
be considered.  For example if you define throw_exception as terminal,
then any method of that name will be terminal, regardless of class.
Just put something like this in your
\&\fI.perlcriticrc\fR:
.PP
.Vb 2
\&    [Subroutines::RequireFinalReturn]
\&    terminal_methods = throw_exception
.Ve
.SH BUGS
.IX Header "BUGS"
We do not look for returns inside ternary operators.  That
construction is too complicated to analyze right now.  Besides, a
better form is the return outside of the ternary like this: \f(CW\*(C`return
foo ? 1 : bar ? 2 : 3\*(C'\fR
.SH AUTHOR
.IX Header "AUTHOR"
Chris Dolan <cdolan@cpan.org>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 2005\-2023 Chris Dolan.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.  The full text of this license
can be found in the LICENSE file included with this module.