1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2025 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 case TokenTypes.METHOD_DEF:
164 case TokenTypes.LAMBDA:
165 leave(ast);
166 break;
167 case TokenTypes.LITERAL_RETURN:
168 // Do nothing
169 break;
170 default:
171 throw new IllegalStateException(ast.toString());
172 }
173 }
174
175 /**
176 * Creates new method context and places old one on the stack.
177 *
178 * @param ast method definition for check.
179 */
180 private void visitMethodDef(DetailAST ast) {
181 contextStack.push(context);
182 final DetailAST methodNameAST = ast.findFirstToken(TokenTypes.IDENT);
183 final boolean check = !format.matcher(methodNameAST.getText()).find();
184 context = new Context(check);
185 }
186
187 /**
188 * Checks number of return statements and restore previous context.
189 *
190 * @param ast node to leave.
191 */
192 private void leave(DetailAST ast) {
193 context.checkCount(ast);
194 context = contextStack.pop();
195 }
196
197 /**
198 * Creates new lambda context and places old one on the stack.
199 */
200 private void visitLambda() {
201 contextStack.push(context);
202 context = new Context(true);
203 }
204
205 /**
206 * Examines the return statement and tells context about it.
207 *
208 * @param ast return statement to check.
209 */
210 private void visitReturn(DetailAST ast) {
211 // we can't identify which max to use for lambdas, so we can only assign
212 // after the first return statement is seen
213 if (ast.getFirstChild().getType() == TokenTypes.SEMI) {
214 context.visitLiteralReturn(maxForVoid, Boolean.TRUE);
215 }
216 else {
217 context.visitLiteralReturn(max, Boolean.FALSE);
218 }
219 }
220
221 /**
222 * Class to encapsulate information about one method.
223 */
224 private final class Context {
225
226 /** Whether we should check this method or not. */
227 private final boolean checking;
228 /** Counter for return statements. */
229 private int count;
230 /** Maximum allowed number of return statements. */
231 private Integer maxAllowed;
232 /** Identifies if context is void. */
233 private boolean isVoidContext;
234
235 /**
236 * Creates new method context.
237 *
238 * @param checking should we check this method or not
239 */
240 private Context(boolean checking) {
241 this.checking = checking;
242 }
243
244 /**
245 * Increase the number of return statements and set context return type.
246 *
247 * @param maxAssigned Maximum allowed number of return statements.
248 * @param voidReturn Identifies if context is void.
249 */
250 public void visitLiteralReturn(int maxAssigned, Boolean voidReturn) {
251 isVoidContext = voidReturn;
252 maxAllowed = maxAssigned;
253
254 ++count;
255 }
256
257 /**
258 * Checks if number of return statements in the method are more
259 * than allowed.
260 *
261 * @param ast method def associated with this context.
262 */
263 public void checkCount(DetailAST ast) {
264 if (checking && maxAllowed != null && count > maxAllowed) {
265 if (isVoidContext) {
266 log(ast, MSG_KEY_VOID, count, maxAllowed);
267 }
268 else {
269 log(ast, MSG_KEY, count, maxAllowed);
270 }
271 }
272 }
273
274 }
275
276 }