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.naming;
21
22 import java.util.ArrayList;
23 import java.util.Arrays;
24 import java.util.HashSet;
25 import java.util.List;
26 import java.util.Set;
27 import java.util.stream.Collectors;
28
29 import com.puppycrawl.tools.checkstyle.StatelessCheck;
30 import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
31 import com.puppycrawl.tools.checkstyle.api.DetailAST;
32 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
33 import com.puppycrawl.tools.checkstyle.utils.CheckUtil;
34 import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
35
36 /**
37 * <div>
38 * Validates abbreviations (consecutive capital letters) length in
39 * identifier name, it also allows to enforce camel case naming. Please read more at
40 * <a href="https://checkstyle.org/styleguides/google-java-style-20250426/javaguide.html#s5.3-camel-case">
41 * Google Style Guide</a> to get to know how to avoid long abbreviations in names.
42 * </div>
43 *
44 * <p>'_' is considered as word separator in identifier name.</p>
45 *
46 * <p>
47 * {@code allowedAbbreviationLength} specifies how many consecutive capital letters are
48 * allowed in the identifier.
49 * A value of <i>3</i> indicates that up to 4 consecutive capital letters are allowed,
50 * one after the other, before a violation is printed. The identifier 'MyTEST' would be
51 * allowed, but 'MyTESTS' would not be.
52 * A value of <i>0</i> indicates that only 1 consecutive capital letter is allowed. This
53 * is what should be used to enforce strict camel casing. The identifier 'MyTest' would
54 * be allowed, but 'MyTEst' would not be.
55 * </p>
56 *
57 * <p>
58 * {@code ignoreFinal}, {@code ignoreStatic}, and {@code ignoreStaticFinal}
59 * control whether variables with the respective modifiers are to be ignored.
60 * Note that a variable that is both static and final will always be considered under
61 * {@code ignoreStaticFinal} only, regardless of the values of {@code ignoreFinal}
62 * and {@code ignoreStatic}. So for example if {@code ignoreStatic} is true but
63 * {@code ignoreStaticFinal} is false, then static final variables will not be ignored.
64 * </p>
65 *
66 * @since 5.8
67 */
68 @StatelessCheck
69 public class AbbreviationAsWordInNameCheck extends AbstractCheck {
70
71 /**
72 * Warning message key.
73 */
74 public static final String MSG_KEY = "abbreviation.as.word";
75
76 /**
77 * The default value of "allowedAbbreviationLength" option.
78 */
79 private static final int DEFAULT_ALLOWED_ABBREVIATIONS_LENGTH = 3;
80
81 /**
82 * Indicate the number of consecutive capital letters allowed in
83 * targeted identifiers (abbreviations in the classes, interfaces, variables
84 * and methods names, ... ).
85 */
86 private int allowedAbbreviationLength =
87 DEFAULT_ALLOWED_ABBREVIATIONS_LENGTH;
88
89 /**
90 * Specify abbreviations that must be skipped for checking.
91 */
92 private Set<String> allowedAbbreviations = new HashSet<>();
93
94 /** Allow to skip variables with {@code final} modifier. */
95 private boolean ignoreFinal = true;
96
97 /** Allow to skip variables with {@code static} modifier. */
98 private boolean ignoreStatic = true;
99
100 /** Allow to skip variables with both {@code static} and {@code final} modifiers. */
101 private boolean ignoreStaticFinal = true;
102
103 /**
104 * Allow to ignore methods tagged with {@code @Override} annotation (that
105 * usually mean inherited name).
106 */
107 private boolean ignoreOverriddenMethods = true;
108
109 /**
110 * Setter to allow to skip variables with {@code final} modifier.
111 *
112 * @param ignoreFinal
113 * Defines if ignore variables with 'final' modifier or not.
114 * @since 5.8
115 */
116 public void setIgnoreFinal(boolean ignoreFinal) {
117 this.ignoreFinal = ignoreFinal;
118 }
119
120 /**
121 * Setter to allow to skip variables with {@code static} modifier.
122 *
123 * @param ignoreStatic
124 * Defines if ignore variables with 'static' modifier or not.
125 * @since 5.8
126 */
127 public void setIgnoreStatic(boolean ignoreStatic) {
128 this.ignoreStatic = ignoreStatic;
129 }
130
131 /**
132 * Setter to allow to skip variables with both {@code static} and {@code final} modifiers.
133 *
134 * @param ignoreStaticFinal
135 * Defines if ignore variables with both 'static' and 'final' modifiers or not.
136 * @since 8.32
137 */
138 public void setIgnoreStaticFinal(boolean ignoreStaticFinal) {
139 this.ignoreStaticFinal = ignoreStaticFinal;
140 }
141
142 /**
143 * Setter to allow to ignore methods tagged with {@code @Override}
144 * annotation (that usually mean inherited name).
145 *
146 * @param ignoreOverriddenMethods
147 * Defines if ignore methods with "@Override" annotation or not.
148 * @since 5.8
149 */
150 public void setIgnoreOverriddenMethods(boolean ignoreOverriddenMethods) {
151 this.ignoreOverriddenMethods = ignoreOverriddenMethods;
152 }
153
154 /**
155 * Setter to indicate the number of consecutive capital letters allowed
156 * in targeted identifiers (abbreviations in the classes, interfaces,
157 * variables and methods names, ... ).
158 *
159 * @param allowedAbbreviationLength amount of allowed capital letters in
160 * abbreviation.
161 * @since 5.8
162 */
163 public void setAllowedAbbreviationLength(int allowedAbbreviationLength) {
164 this.allowedAbbreviationLength = allowedAbbreviationLength;
165 }
166
167 /**
168 * Setter to specify abbreviations that must be skipped for checking.
169 *
170 * @param allowedAbbreviations abbreviations that must be
171 * skipped from checking.
172 * @since 5.8
173 */
174 public void setAllowedAbbreviations(String... allowedAbbreviations) {
175 if (allowedAbbreviations != null) {
176 this.allowedAbbreviations =
177 Arrays.stream(allowedAbbreviations).collect(Collectors.toUnmodifiableSet());
178 }
179 }
180
181 @Override
182 public int[] getDefaultTokens() {
183 return new int[] {
184 TokenTypes.CLASS_DEF,
185 TokenTypes.INTERFACE_DEF,
186 TokenTypes.ENUM_DEF,
187 TokenTypes.ANNOTATION_DEF,
188 TokenTypes.ANNOTATION_FIELD_DEF,
189 TokenTypes.PARAMETER_DEF,
190 TokenTypes.VARIABLE_DEF,
191 TokenTypes.METHOD_DEF,
192 TokenTypes.PATTERN_VARIABLE_DEF,
193 TokenTypes.RECORD_DEF,
194 TokenTypes.RECORD_COMPONENT_DEF,
195 };
196 }
197
198 @Override
199 public int[] getAcceptableTokens() {
200 return new int[] {
201 TokenTypes.CLASS_DEF,
202 TokenTypes.INTERFACE_DEF,
203 TokenTypes.ENUM_DEF,
204 TokenTypes.ANNOTATION_DEF,
205 TokenTypes.ANNOTATION_FIELD_DEF,
206 TokenTypes.PARAMETER_DEF,
207 TokenTypes.VARIABLE_DEF,
208 TokenTypes.METHOD_DEF,
209 TokenTypes.ENUM_CONSTANT_DEF,
210 TokenTypes.PATTERN_VARIABLE_DEF,
211 TokenTypes.RECORD_DEF,
212 TokenTypes.RECORD_COMPONENT_DEF,
213 };
214 }
215
216 @Override
217 public int[] getRequiredTokens() {
218 return CommonUtil.EMPTY_INT_ARRAY;
219 }
220
221 @Override
222 public void visitToken(DetailAST ast) {
223 if (!isIgnoreSituation(ast)) {
224 final DetailAST nameAst = ast.findFirstToken(TokenTypes.IDENT);
225 final String typeName = nameAst.getText();
226
227 final String abbr = getDisallowedAbbreviation(typeName);
228 if (abbr != null) {
229 log(nameAst, MSG_KEY, typeName, allowedAbbreviationLength + 1);
230 }
231 }
232 }
233
234 /**
235 * Checks if it is an ignore situation.
236 *
237 * @param ast input DetailAST node.
238 * @return true if it is an ignore situation found for given input DetailAST
239 * node.
240 */
241 private boolean isIgnoreSituation(DetailAST ast) {
242 final DetailAST modifiers = ast.getFirstChild();
243
244 final boolean result;
245 if (ast.getType() == TokenTypes.VARIABLE_DEF) {
246 if (isInterfaceDeclaration(ast)) {
247 // field declarations in interface are static/final
248 result = ignoreStaticFinal;
249 }
250 else {
251 result = hasIgnoredModifiers(modifiers);
252 }
253 }
254 else if (ast.getType() == TokenTypes.METHOD_DEF) {
255 result = ignoreOverriddenMethods && hasOverrideAnnotation(modifiers);
256 }
257 else {
258 result = CheckUtil.isReceiverParameter(ast);
259 }
260 return result;
261 }
262
263 /**
264 * Checks if a variable is to be ignored based on its modifiers.
265 *
266 * @param modifiers modifiers of the variable to be checked
267 * @return true if there is a modifier to be ignored
268 */
269 private boolean hasIgnoredModifiers(DetailAST modifiers) {
270 final boolean isStatic = modifiers.findFirstToken(TokenTypes.LITERAL_STATIC) != null;
271 final boolean isFinal = modifiers.findFirstToken(TokenTypes.FINAL) != null;
272 final boolean result;
273 if (isStatic && isFinal) {
274 result = ignoreStaticFinal;
275 }
276 else {
277 result = ignoreStatic && isStatic || ignoreFinal && isFinal;
278 }
279 return result;
280 }
281
282 /**
283 * Check that variable definition in interface or @interface definition.
284 *
285 * @param variableDefAst variable definition.
286 * @return true if variable definition(variableDefAst) is in interface
287 * or @interface definition.
288 */
289 private static boolean isInterfaceDeclaration(DetailAST variableDefAst) {
290 boolean result = false;
291 final DetailAST astBlock = variableDefAst.getParent();
292
293 if (astBlock.getType() != TokenTypes.COMPACT_COMPILATION_UNIT) {
294 final DetailAST astParent2 = astBlock.getParent();
295
296 if (astParent2.getType() == TokenTypes.INTERFACE_DEF
297 || astParent2.getType() == TokenTypes.ANNOTATION_DEF) {
298 result = true;
299 }
300 }
301 return result;
302 }
303
304 /**
305 * Checks that the method has "@Override" annotation.
306 *
307 * @param methodModifiersAST
308 * A DetailAST nod is related to the given method modifiers
309 * (MODIFIERS type).
310 * @return true if method has "@Override" annotation.
311 */
312 private static boolean hasOverrideAnnotation(DetailAST methodModifiersAST) {
313 boolean result = false;
314 for (DetailAST child : getChildren(methodModifiersAST)) {
315 final DetailAST annotationIdent = child.findFirstToken(TokenTypes.IDENT);
316
317 if (annotationIdent != null && "Override".equals(annotationIdent.getText())) {
318 result = true;
319 break;
320 }
321 }
322 return result;
323 }
324
325 /**
326 * Gets the disallowed abbreviation contained in given String.
327 *
328 * @param str
329 * the given String.
330 * @return the disallowed abbreviation contained in given String as a
331 * separate String.
332 */
333 private String getDisallowedAbbreviation(String str) {
334 int beginIndex = 0;
335 boolean abbrStarted = false;
336 String result = null;
337
338 for (int index = 0; index < str.length(); index++) {
339 final char symbol = str.charAt(index);
340
341 if (Character.isUpperCase(symbol)) {
342 if (!abbrStarted) {
343 abbrStarted = true;
344 beginIndex = index;
345 }
346 }
347 else if (abbrStarted) {
348 abbrStarted = false;
349
350 final int endIndex;
351 final int allowedLength;
352 if (symbol == '_') {
353 endIndex = index;
354 allowedLength = allowedAbbreviationLength + 1;
355 }
356 else {
357 endIndex = index - 1;
358 allowedLength = allowedAbbreviationLength;
359 }
360 result = getAbbreviationIfIllegal(str, beginIndex, endIndex, allowedLength);
361 if (result != null) {
362 break;
363 }
364 beginIndex = -1;
365 }
366 }
367 // if abbreviation at the end of name (example: scaleX)
368 if (abbrStarted) {
369 final int endIndex = str.length() - 1;
370 result = getAbbreviationIfIllegal(str, beginIndex, endIndex, allowedAbbreviationLength);
371 }
372 return result;
373 }
374
375 /**
376 * Get Abbreviation if it is illegal, where {@code beginIndex} and {@code endIndex} are
377 * inclusive indexes of a sequence of consecutive upper-case characters.
378 *
379 * @param str name
380 * @param beginIndex begin index
381 * @param endIndex end index
382 * @param allowedLength maximum allowed length for Abbreviation
383 * @return the abbreviation if it is bigger than required and not in the
384 * ignore list, otherwise {@code null}
385 */
386 private String getAbbreviationIfIllegal(String str, int beginIndex, int endIndex,
387 int allowedLength) {
388 String result = null;
389 final int abbrLength = endIndex - beginIndex;
390 if (abbrLength > allowedLength) {
391 final String abbr = getAbbreviation(str, beginIndex, endIndex);
392 if (!allowedAbbreviations.contains(abbr)) {
393 result = abbr;
394 }
395 }
396 return result;
397 }
398
399 /**
400 * Gets the abbreviation, where {@code beginIndex} and {@code endIndex} are
401 * inclusive indexes of a sequence of consecutive upper-case characters.
402 *
403 * <p>
404 * The character at {@code endIndex} is only included in the abbreviation if
405 * it is the last character in the string; otherwise it is usually the first
406 * capital in the next word.
407 * </p>
408 *
409 * <p>
410 * For example, {@code getAbbreviation("getXMLParser", 3, 6)} returns "XML"
411 * (not "XMLP"), and so does {@code getAbbreviation("parseXML", 5, 7)}.
412 * </p>
413 *
414 * @param str name
415 * @param beginIndex begin index
416 * @param endIndex end index
417 * @return the specified abbreviation
418 */
419 private static String getAbbreviation(String str, int beginIndex, int endIndex) {
420 final String result;
421 if (endIndex == str.length() - 1) {
422 result = str.substring(beginIndex);
423 }
424 else {
425 result = str.substring(beginIndex, endIndex);
426 }
427 return result;
428 }
429
430 /**
431 * Gets all the children which are one level below on the current DetailAST
432 * parent node.
433 *
434 * @param node
435 * Current parent node.
436 * @return The list of children one level below on the current parent node.
437 */
438 private static List<DetailAST> getChildren(final DetailAST node) {
439 final List<DetailAST> result = new ArrayList<>();
440 DetailAST curNode = node.getFirstChild();
441 while (curNode != null) {
442 result.add(curNode);
443 curNode = curNode.getNextSibling();
444 }
445 return result;
446 }
447
448 }