Source code

001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2025 the original author or authors.
004//
005// This library is free software; you can redistribute it and/or
006// modify it under the terms of the GNU Lesser General Public
007// License as published by the Free Software Foundation; either
008// version 2.1 of the License, or (at your option) any later version.
009//
010// This library is distributed in the hope that it will be useful,
011// but WITHOUT ANY WARRANTY; without even the implied warranty of
012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013// Lesser General Public License for more details.
014//
015// You should have received a copy of the GNU Lesser General Public
016// License along with this library; if not, write to the Free Software
017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
018///////////////////////////////////////////////////////////////////////////////////////////////
019
020package com.puppycrawl.tools.checkstyle.checks.metrics;
021
022import java.util.ArrayDeque;
023import java.util.Deque;
024
025import com.puppycrawl.tools.checkstyle.FileStatefulCheck;
026import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
027import com.puppycrawl.tools.checkstyle.api.DetailAST;
028import com.puppycrawl.tools.checkstyle.api.TokenTypes;
029import com.puppycrawl.tools.checkstyle.utils.CheckUtil;
030
031/**
032 * <div>
033 * Restricts the number of boolean operators ({@code &amp;&amp;}, {@code ||},
034 * {@code &amp;}, {@code |} and {@code ^}) in an expression.
035 * </div>
036 *
037 * <p>
038 * Rationale: Too many conditions leads to code that is difficult to read
039 * and hence debug and maintain.
040 * </p>
041 *
042 * <p>
043 * Note that the operators {@code &amp;} and {@code |} are not only integer bitwise
044 * operators, they are also the
045 * <a href="https://docs.oracle.com/javase/specs/jls/se11/html/jls-15.html#jls-15.22.2">
046 * non-shortcut versions</a> of the boolean operators {@code &amp;&amp;} and {@code ||}.
047 * </p>
048 *
049 * <p>
050 * Note that {@code &amp;}, {@code |} and {@code ^} are not checked if they are part
051 * of constructor or method call because they can be applied to non-boolean
052 * variables and Checkstyle does not know types of methods from different classes.
053 * </p>
054 * <ul>
055 * <li>
056 * Property {@code max} - Specify the maximum number of boolean operations
057 * allowed in one expression.
058 * Type is {@code int}.
059 * Default value is {@code 3}.
060 * </li>
061 * <li>
062 * Property {@code tokens} - tokens to check
063 * Type is {@code java.lang.String[]}.
064 * Validation type is {@code tokenSet}.
065 * Default value is:
066 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LAND">
067 * LAND</a>,
068 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#BAND">
069 * BAND</a>,
070 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LOR">
071 * LOR</a>,
072 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#BOR">
073 * BOR</a>,
074 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#BXOR">
075 * BXOR</a>.
076 * </li>
077 * </ul>
078 *
079 * <p>
080 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
081 * </p>
082 *
083 * <p>
084 * Violation Message Keys:
085 * </p>
086 * <ul>
087 * <li>
088 * {@code booleanExpressionComplexity}
089 * </li>
090 * </ul>
091 *
092 * @since 3.4
093 */
094@FileStatefulCheck
095public final class BooleanExpressionComplexityCheck extends AbstractCheck {
096
097    /**
098     * A key is pointing to the warning message text in "messages.properties"
099     * file.
100     */
101    public static final String MSG_KEY = "booleanExpressionComplexity";
102
103    /** Default allowed complexity. */
104    private static final int DEFAULT_MAX = 3;
105
106    /** Stack of contexts. */
107    private final Deque<Context> contextStack = new ArrayDeque<>();
108    /** Specify the maximum number of boolean operations allowed in one expression. */
109    private int max;
110    /** Current context. */
111    private Context context = new Context(false);
112
113    /** Creates new instance of the check. */
114    public BooleanExpressionComplexityCheck() {
115        max = DEFAULT_MAX;
116    }
117
118    @Override
119    public int[] getDefaultTokens() {
120        return new int[] {
121            TokenTypes.CTOR_DEF,
122            TokenTypes.METHOD_DEF,
123            TokenTypes.EXPR,
124            TokenTypes.LAND,
125            TokenTypes.BAND,
126            TokenTypes.LOR,
127            TokenTypes.BOR,
128            TokenTypes.BXOR,
129            TokenTypes.COMPACT_CTOR_DEF,
130        };
131    }
132
133    @Override
134    public int[] getRequiredTokens() {
135        return new int[] {
136            TokenTypes.CTOR_DEF,
137            TokenTypes.METHOD_DEF,
138            TokenTypes.EXPR,
139            TokenTypes.COMPACT_CTOR_DEF,
140        };
141    }
142
143    @Override
144    public int[] getAcceptableTokens() {
145        return new int[] {
146            TokenTypes.CTOR_DEF,
147            TokenTypes.METHOD_DEF,
148            TokenTypes.EXPR,
149            TokenTypes.LAND,
150            TokenTypes.BAND,
151            TokenTypes.LOR,
152            TokenTypes.BOR,
153            TokenTypes.BXOR,
154            TokenTypes.COMPACT_CTOR_DEF,
155        };
156    }
157
158    /**
159     * Setter to specify the maximum number of boolean operations allowed in one expression.
160     *
161     * @param max new maximum allowed complexity.
162     * @since 3.4
163     */
164    public void setMax(int max) {
165        this.max = max;
166    }
167
168    @Override
169    public void visitToken(DetailAST ast) {
170        switch (ast.getType()) {
171            case TokenTypes.CTOR_DEF:
172            case TokenTypes.METHOD_DEF:
173            case TokenTypes.COMPACT_CTOR_DEF:
174                visitMethodDef(ast);
175                break;
176            case TokenTypes.EXPR:
177                visitExpr();
178                break;
179            case TokenTypes.BOR:
180                if (!isPipeOperator(ast) && !isPassedInParameter(ast)) {
181                    context.visitBooleanOperator();
182                }
183                break;
184            case TokenTypes.BAND:
185            case TokenTypes.BXOR:
186                if (!isPassedInParameter(ast)) {
187                    context.visitBooleanOperator();
188                }
189                break;
190            case TokenTypes.LAND:
191            case TokenTypes.LOR:
192                context.visitBooleanOperator();
193                break;
194            default:
195                throw new IllegalArgumentException("Unknown type: " + ast);
196        }
197    }
198
199    /**
200     * Checks if logical operator is part of constructor or method call.
201     *
202     * @param logicalOperator logical operator
203     * @return true if logical operator is part of constructor or method call
204     */
205    private static boolean isPassedInParameter(DetailAST logicalOperator) {
206        return logicalOperator.getParent().getParent().getType() == TokenTypes.ELIST;
207    }
208
209    /**
210     * Checks if {@link TokenTypes#BOR binary OR} is applied to exceptions
211     * in
212     * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-14.html#jls-14.20">
213     * multi-catch</a> (pipe-syntax).
214     *
215     * @param binaryOr {@link TokenTypes#BOR binary or}
216     * @return true if binary or is applied to exceptions in multi-catch.
217     */
218    private static boolean isPipeOperator(DetailAST binaryOr) {
219        return binaryOr.getParent().getType() == TokenTypes.TYPE;
220    }
221
222    @Override
223    public void leaveToken(DetailAST ast) {
224        switch (ast.getType()) {
225            case TokenTypes.CTOR_DEF:
226            case TokenTypes.METHOD_DEF:
227            case TokenTypes.COMPACT_CTOR_DEF:
228                leaveMethodDef();
229                break;
230            case TokenTypes.EXPR:
231                leaveExpr(ast);
232                break;
233            default:
234                // Do nothing
235        }
236    }
237
238    /**
239     * Creates new context for a given method.
240     *
241     * @param ast a method we start to check.
242     */
243    private void visitMethodDef(DetailAST ast) {
244        contextStack.push(context);
245        final boolean check = !CheckUtil.isEqualsMethod(ast);
246        context = new Context(check);
247    }
248
249    /** Removes old context. */
250    private void leaveMethodDef() {
251        context = contextStack.pop();
252    }
253
254    /** Creates and pushes new context. */
255    private void visitExpr() {
256        contextStack.push(context);
257        context = new Context(context.isChecking());
258    }
259
260    /**
261     * Restores previous context.
262     *
263     * @param ast expression we leave.
264     */
265    private void leaveExpr(DetailAST ast) {
266        context.checkCount(ast);
267        context = contextStack.pop();
268    }
269
270    /**
271     * Represents context (method/expression) in which we check complexity.
272     *
273     */
274    private final class Context {
275
276        /**
277         * Should we perform check in current context or not.
278         * Usually false if we are inside equals() method.
279         */
280        private final boolean checking;
281        /** Count of boolean operators. */
282        private int count;
283
284        /**
285         * Creates new instance.
286         *
287         * @param checking should we check in current context or not.
288         */
289        private Context(boolean checking) {
290            this.checking = checking;
291        }
292
293        /**
294         * Getter for checking property.
295         *
296         * @return should we check in current context or not.
297         */
298        public boolean isChecking() {
299            return checking;
300        }
301
302        /** Increases operator counter. */
303        public void visitBooleanOperator() {
304            ++count;
305        }
306
307        /**
308         * Checks if we violate maximum allowed complexity.
309         *
310         * @param ast a node we check now.
311         */
312        public void checkCount(DetailAST ast) {
313            if (checking && count > max) {
314                final DetailAST parentAST = ast.getParent();
315
316                log(parentAST, MSG_KEY, count, max);
317            }
318        }
319
320    }
321
322}