1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2026 the original author or authors.
4 //
5 // This library is free software; you can redistribute it and/or
6 // modify it under the terms of the GNU Lesser General Public
7 // License as published by the Free Software Foundation; either
8 // version 2.1 of the License, or (at your option) any later version.
9 //
10 // This library is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 // Lesser General Public License for more details.
14 //
15 // You should have received a copy of the GNU Lesser General Public
16 // License along with this library; if not, write to the Free Software
17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 ///////////////////////////////////////////////////////////////////////////////////////////////
19
20 package com.puppycrawl.tools.checkstyle.checks.coding;
21
22 import java.util.ArrayDeque;
23 import java.util.Deque;
24 import java.util.regex.Pattern;
25
26 import com.puppycrawl.tools.checkstyle.FileStatefulCheck;
27 import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
28 import com.puppycrawl.tools.checkstyle.api.DetailAST;
29 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
30
31 /**
32 * <div>
33 * Restricts the number of return statements in methods, constructors and lambda expressions.
34 * Ignores specified methods ({@code equals} by default).
35 * </div>
36 *
37 * <p>
38 * <b>max</b> property will only check returns in methods and lambdas that
39 * return a specific value (Ex: 'return 1;').
40 * </p>
41 *
42 * <p>
43 * <b>maxForVoid</b> property will only check returns in methods, constructors,
44 * and lambdas that have no return type (IE 'return;'). It will only count
45 * visible return statements. Return statements not normally written, but
46 * implied, at the end of the method/constructor definition will not be taken
47 * into account. To disallow "return;" in void return type methods, use a value
48 * of 0.
49 * </p>
50 *
51 * <p>
52 * Rationale: Too many return points can mean that code is
53 * attempting to do too much or may be difficult to understand.
54 * </p>
55 *
56 * @since 3.2
57 */
58 @FileStatefulCheck
59 public final class ReturnCountCheck extends AbstractCheck {
60
61 /**
62 * A key is pointing to the warning message text in "messages.properties"
63 * file.
64 */
65 public static final String MSG_KEY = "return.count";
66 /**
67 * A key pointing to the warning message text in "messages.properties"
68 * file.
69 */
70 public static final String MSG_KEY_VOID = "return.countVoid";
71
72 /** Stack of method contexts. */
73 private final Deque<Context> contextStack = new ArrayDeque<>();
74
75 /** Specify method names to ignore. */
76 private Pattern format = Pattern.compile("^equals$");
77
78 /** Specify maximum allowed number of return statements in non-void methods/lambdas. */
79 private int max = 2;
80 /** Specify maximum allowed number of return statements in void methods/constructors/lambdas. */
81 private int maxForVoid = 1;
82 /** Current method context. */
83 private Context context;
84
85 @Override
86 public int[] getDefaultTokens() {
87 return new int[] {
88 TokenTypes.CTOR_DEF,
89 TokenTypes.METHOD_DEF,
90 TokenTypes.LAMBDA,
91 TokenTypes.LITERAL_RETURN,
92 };
93 }
94
95 @Override
96 public int[] getRequiredTokens() {
97 return new int[] {TokenTypes.LITERAL_RETURN};
98 }
99
100 @Override
101 public int[] getAcceptableTokens() {
102 return new int[] {
103 TokenTypes.CTOR_DEF,
104 TokenTypes.METHOD_DEF,
105 TokenTypes.LAMBDA,
106 TokenTypes.LITERAL_RETURN,
107 };
108 }
109
110 /**
111 * Setter to specify method names to ignore.
112 *
113 * @param pattern a pattern.
114 * @since 3.4
115 */
116 public void setFormat(Pattern pattern) {
117 format = pattern;
118 }
119
120 /**
121 * Setter to specify maximum allowed number of return statements
122 * in non-void methods/lambdas.
123 *
124 * @param max maximum allowed number of return statements.
125 * @since 3.2
126 */
127 public void setMax(int max) {
128 this.max = max;
129 }
130
131 /**
132 * Setter to specify maximum allowed number of return statements
133 * in void methods/constructors/lambdas.
134 *
135 * @param maxForVoid maximum allowed number of return statements for void methods.
136 * @since 6.19
137 */
138 public void setMaxForVoid(int maxForVoid) {
139 this.maxForVoid = maxForVoid;
140 }
141
142 @Override
143 public void beginTree(DetailAST rootAST) {
144 context = new Context(false);
145 contextStack.clear();
146 }
147
148 @Override
149 public void visitToken(DetailAST ast) {
150 switch (ast.getType()) {
151 case TokenTypes.CTOR_DEF,
152 TokenTypes.METHOD_DEF -> visitMethodDef(ast);
153 case TokenTypes.LAMBDA -> visitLambda();
154 case TokenTypes.LITERAL_RETURN -> visitReturn(ast);
155 default -> throw new IllegalStateException(ast.toString());
156 }
157 }
158
159 @Override
160 public void leaveToken(DetailAST ast) {
161 switch (ast.getType()) {
162 case TokenTypes.CTOR_DEF,
163 TokenTypes.METHOD_DEF,
164 TokenTypes.LAMBDA -> leave(ast);
165 case TokenTypes.LITERAL_RETURN -> {
166 // Do nothing
167 }
168 default -> throw new IllegalStateException(ast.toString());
169 }
170 }
171
172 /**
173 * Creates new method context and places old one on the stack.
174 *
175 * @param ast method definition for check.
176 */
177 private void visitMethodDef(DetailAST ast) {
178 contextStack.push(context);
179 final DetailAST methodNameAST = ast.findFirstToken(TokenTypes.IDENT);
180 final boolean check = !format.matcher(methodNameAST.getText()).find();
181 context = new Context(check);
182 }
183
184 /**
185 * Checks number of return statements and restore previous context.
186 *
187 * @param ast node to leave.
188 */
189 private void leave(DetailAST ast) {
190 context.checkCount(ast);
191 context = contextStack.pop();
192 }
193
194 /**
195 * Creates new lambda context and places old one on the stack.
196 */
197 private void visitLambda() {
198 contextStack.push(context);
199 context = new Context(true);
200 }
201
202 /**
203 * Examines the return statement and tells context about it.
204 *
205 * @param ast return statement to check.
206 */
207 private void visitReturn(DetailAST ast) {
208 // we can't identify which max to use for lambdas, so we can only assign
209 // after the first return statement is seen
210 if (ast.getFirstChild().getType() == TokenTypes.SEMI) {
211 context.visitLiteralReturn(maxForVoid, Boolean.TRUE);
212 }
213 else {
214 context.visitLiteralReturn(max, Boolean.FALSE);
215 }
216 }
217
218 /**
219 * Class to encapsulate information about one method.
220 */
221 private final class Context {
222
223 /** Whether we should check this method or not. */
224 private final boolean checking;
225 /** Counter for return statements. */
226 private int count;
227 /** Maximum allowed number of return statements. */
228 private Integer maxAllowed;
229 /** Identifies if context is void. */
230 private boolean isVoidContext;
231
232 /**
233 * Creates new method context.
234 *
235 * @param checking should we check this method or not
236 */
237 private Context(boolean checking) {
238 this.checking = checking;
239 }
240
241 /**
242 * Increase the number of return statements and set context return type.
243 *
244 * @param maxAssigned Maximum allowed number of return statements.
245 * @param voidReturn Identifies if context is void.
246 */
247 /* package */ void visitLiteralReturn(int maxAssigned, Boolean voidReturn) {
248 isVoidContext = voidReturn;
249 maxAllowed = maxAssigned;
250
251 ++count;
252 }
253
254 /**
255 * Checks if number of return statements in the method are more
256 * than allowed.
257 *
258 * @param ast method def associated with this context.
259 */
260 /* package */ void checkCount(DetailAST ast) {
261 if (checking && maxAllowed != null && count > maxAllowed) {
262 if (isVoidContext) {
263 log(ast, MSG_KEY_VOID, count, maxAllowed);
264 }
265 else {
266 log(ast, MSG_KEY, count, maxAllowed);
267 }
268 }
269 }
270
271 }
272
273 }