View Javadoc
1   ////////////////////////////////////////////////////////////////////////////////
2   // checkstyle: Checks Java source code for adherence to a set of rules.
3   // Copyright (C) 2001-2017 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.Arrays;
23  import java.util.HashSet;
24  import java.util.LinkedList;
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.CheckUtils;
34  import com.puppycrawl.tools.checkstyle.utils.CommonUtils;
35  
36  /**
37   * <p>
38   * The Check validate abbreviations(consecutive capital letters) length in
39   * identifier name, it also allows to enforce camel case naming. Please read more at
40   * <a href=
41   *  "http://checkstyle.sourceforge.net/reports/google-java-style-20170228.html#s5.3-camel-case">
42   * Google Style Guide</a> to get to know how to avoid long abbreviations in names.
43   * </p>
44   * <p>
45   * {@code allowedAbbreviationLength} specifies how many consecutive capital letters are
46   * allowed in the identifier.
47   * A value of <i>3</i> indicates that up to 4 consecutive capital letters are allowed,
48   * one after the other, before a violation is printed. The identifier 'MyTEST' would be
49   * allowed, but 'MyTESTS' would not be.
50   * A value of <i>0</i> indicates that only 1 consecutive capital letter is allowed. This
51   * is what should be used to enforce strict camel casing. The identifier 'MyTest' would
52   * be allowed, but 'MyTEst' would not be.
53   * </p>
54   * <p>
55   * Option {@code allowedAbbreviationLength} indicates on the allowed amount of capital
56   * letters in abbreviations in the classes, interfaces,
57   * variables and methods names. Default value is '3'.
58   * </p>
59   * <p>
60   * Option {@code allowedAbbreviations} - list of abbreviations that
61   * must be skipped for checking. Abbreviations should be separated by comma,
62   * no spaces are allowed.
63   * </p>
64   * <p>
65   * Option {@code ignoreFinal} allow to skip variables with {@code final} modifier.
66   * Default value is {@code true}.
67   * </p>
68   * <p>
69   * Option {@code ignoreStatic} allow to skip variables with {@code static} modifier.
70   * Default value is {@code true}.
71   * </p>
72   * <p>
73   * Option {@code ignoreOverriddenMethod} - Allows to
74   * ignore methods tagged with {@code @Override} annotation
75   * (that usually mean inherited name). Default value is {@code true}.
76   * </p>
77   * Default configuration
78   * <pre>
79   * &lt;module name="AbbreviationAsWordInName" /&gt;
80   * </pre>
81   * <p>
82   * To configure to check variables and classes identifiers, do not ignore
83   * variables with static modifier
84   * and allow no abbreviations (enforce camel case phrase) but allow XML and URL abbreviations.
85   * </p>
86   * <pre>
87   * &lt;module name="AbbreviationAsWordInName"&gt;
88   *     &lt;property name="tokens" value="VARIABLE_DEF,CLASS_DEF"/&gt;
89   *     &lt;property name="ignoreStatic" value="false"/&gt;
90   *     &lt;property name="allowedAbbreviationLength" value="1"/&gt;
91   *     &lt;property name="allowedAbbreviations" value="XML,URL"/&gt;
92   * &lt;/module&gt;
93   * </pre>
94   *
95   * @author Roman Ivanov, Daniil Yaroslvtsev, Baratali Izmailov
96   */
97  @StatelessCheck
98  public class AbbreviationAsWordInNameCheck extends AbstractCheck {
99  
100     /**
101      * Warning message key.
102      */
103     public static final String MSG_KEY = "abbreviation.as.word";
104 
105     /**
106      * The default value of "allowedAbbreviationLength" option.
107      */
108     private static final int DEFAULT_ALLOWED_ABBREVIATIONS_LENGTH = 3;
109 
110     /**
111      * Variable indicates on the allowed amount of capital letters in
112      * abbreviations in the classes, interfaces, variables and methods names.
113      */
114     private int allowedAbbreviationLength =
115             DEFAULT_ALLOWED_ABBREVIATIONS_LENGTH;
116 
117     /**
118      * Set of allowed abbreviation to ignore in check.
119      */
120     private Set<String> allowedAbbreviations = new HashSet<>();
121 
122     /** Allows to ignore variables with 'final' modifier. */
123     private boolean ignoreFinal = true;
124 
125     /** Allows to ignore variables with 'static' modifier. */
126     private boolean ignoreStatic = true;
127 
128     /** Allows to ignore methods with '@Override' annotation. */
129     private boolean ignoreOverriddenMethods = true;
130 
131     /**
132      * Sets ignore option for variables with 'final' modifier.
133      * @param ignoreFinal
134      *        Defines if ignore variables with 'final' modifier or not.
135      */
136     public void setIgnoreFinal(boolean ignoreFinal) {
137         this.ignoreFinal = ignoreFinal;
138     }
139 
140     /**
141      * Sets ignore option for variables with 'static' modifier.
142      * @param ignoreStatic
143      *        Defines if ignore variables with 'static' modifier or not.
144      */
145     public void setIgnoreStatic(boolean ignoreStatic) {
146         this.ignoreStatic = ignoreStatic;
147     }
148 
149     /**
150      * Sets ignore option for methods with "@Override" annotation.
151      * @param ignoreOverriddenMethods
152      *        Defines if ignore methods with "@Override" annotation or not.
153      */
154     public void setIgnoreOverriddenMethods(boolean ignoreOverriddenMethods) {
155         this.ignoreOverriddenMethods = ignoreOverriddenMethods;
156     }
157 
158     /**
159      * Allowed abbreviation length in names.
160      * @param allowedAbbreviationLength
161      *            amount of allowed capital letters in abbreviation.
162      */
163     public void setAllowedAbbreviationLength(int allowedAbbreviationLength) {
164         this.allowedAbbreviationLength = allowedAbbreviationLength;
165     }
166 
167     /**
168      * Set a list of abbreviations that must be skipped for checking.
169      * Abbreviations should be separated by comma, no spaces is allowed.
170      * @param allowedAbbreviations
171      *        an string of abbreviations that must be skipped from checking,
172      *        each abbreviation separated by comma.
173      */
174     public void setAllowedAbbreviations(String... allowedAbbreviations) {
175         if (allowedAbbreviations != null) {
176             this.allowedAbbreviations =
177                 Arrays.stream(allowedAbbreviations).collect(Collectors.toSet());
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         };
193     }
194 
195     @Override
196     public int[] getAcceptableTokens() {
197         return new int[] {
198             TokenTypes.CLASS_DEF,
199             TokenTypes.INTERFACE_DEF,
200             TokenTypes.ENUM_DEF,
201             TokenTypes.ANNOTATION_DEF,
202             TokenTypes.ANNOTATION_FIELD_DEF,
203             TokenTypes.PARAMETER_DEF,
204             TokenTypes.VARIABLE_DEF,
205             TokenTypes.METHOD_DEF,
206             TokenTypes.ENUM_CONSTANT_DEF,
207         };
208     }
209 
210     @Override
211     public int[] getRequiredTokens() {
212         return CommonUtils.EMPTY_INT_ARRAY;
213     }
214 
215     @Override
216     public void visitToken(DetailAST ast) {
217 
218         if (!isIgnoreSituation(ast)) {
219 
220             final DetailAST nameAst = ast.findFirstToken(TokenTypes.IDENT);
221             final String typeName = nameAst.getText();
222 
223             final String abbr = getDisallowedAbbreviation(typeName);
224             if (abbr != null) {
225                 log(nameAst.getLineNo(), MSG_KEY, typeName, allowedAbbreviationLength + 1);
226             }
227         }
228     }
229 
230     /**
231      * Checks if it is an ignore situation.
232      * @param ast input DetailAST node.
233      * @return true if it is an ignore situation found for given input DetailAST
234      *         node.
235      * @noinspection SimplifiableIfStatement
236      */
237     private boolean isIgnoreSituation(DetailAST ast) {
238         final DetailAST modifiers = ast.getFirstChild();
239 
240         final boolean result;
241         if (ast.getType() == TokenTypes.VARIABLE_DEF) {
242             if ((ignoreFinal || ignoreStatic)
243                     && isInterfaceDeclaration(ast)) {
244                 // field declarations in interface are static/final
245                 result = true;
246             }
247             else {
248                 result = ignoreFinal
249                           && modifiers.findFirstToken(TokenTypes.FINAL) != null
250                     || ignoreStatic
251                         && modifiers.findFirstToken(TokenTypes.LITERAL_STATIC) != null;
252             }
253         }
254         else if (ast.getType() == TokenTypes.METHOD_DEF) {
255             result = ignoreOverriddenMethods && hasOverrideAnnotation(modifiers);
256         }
257         else {
258             result = CheckUtils.isReceiverParameter(ast);
259         }
260         return result;
261     }
262 
263     /**
264      * Check that variable definition in interface or @interface definition.
265      * @param variableDefAst variable definition.
266      * @return true if variable definition(variableDefAst) is in interface
267      *     or @interface definition.
268      */
269     private static boolean isInterfaceDeclaration(DetailAST variableDefAst) {
270         boolean result = false;
271         final DetailAST astBlock = variableDefAst.getParent();
272         final DetailAST astParent2 = astBlock.getParent();
273 
274         if (astParent2.getType() == TokenTypes.INTERFACE_DEF
275                 || astParent2.getType() == TokenTypes.ANNOTATION_DEF) {
276             result = true;
277         }
278         return result;
279     }
280 
281     /**
282      * Checks that the method has "@Override" annotation.
283      * @param methodModifiersAST
284      *        A DetailAST nod is related to the given method modifiers
285      *        (MODIFIERS type).
286      * @return true if method has "@Override" annotation.
287      */
288     private static boolean hasOverrideAnnotation(DetailAST methodModifiersAST) {
289         boolean result = false;
290         for (DetailAST child : getChildren(methodModifiersAST)) {
291             if (child.getType() == TokenTypes.ANNOTATION) {
292                 final DetailAST annotationIdent = child.findFirstToken(TokenTypes.IDENT);
293 
294                 if (annotationIdent != null && "Override".equals(annotationIdent.getText())) {
295                     result = true;
296                     break;
297                 }
298             }
299         }
300         return result;
301     }
302 
303     /**
304      * Gets the disallowed abbreviation contained in given String.
305      * @param str
306      *        the given String.
307      * @return the disallowed abbreviation contained in given String as a
308      *         separate String.
309      */
310     private String getDisallowedAbbreviation(String str) {
311         int beginIndex = 0;
312         boolean abbrStarted = false;
313         String result = null;
314 
315         for (int index = 0; index < str.length(); index++) {
316             final char symbol = str.charAt(index);
317 
318             if (Character.isUpperCase(symbol)) {
319                 if (!abbrStarted) {
320                     abbrStarted = true;
321                     beginIndex = index;
322                 }
323             }
324             else if (abbrStarted) {
325                 abbrStarted = false;
326 
327                 final int endIndex = index - 1;
328                 // -1 as a first capital is usually beginning of next word
329                 result = getAbbreviationIfIllegal(str, beginIndex, endIndex);
330                 if (result != null) {
331                     break;
332                 }
333                 beginIndex = -1;
334             }
335         }
336         // if abbreviation at the end of name and it is not single character (example: scaleX)
337         if (abbrStarted && beginIndex != str.length() - 1) {
338             final int endIndex = str.length();
339             result = getAbbreviationIfIllegal(str, beginIndex, endIndex);
340         }
341         return result;
342     }
343 
344     /**
345      * Get Abbreviation if it is illegal.
346      * @param str name
347      * @param beginIndex begin index
348      * @param endIndex end index
349      * @return true is abbreviation is bigger that required and not in ignore list
350      */
351     private String getAbbreviationIfIllegal(String str, int beginIndex, int endIndex) {
352         String result = null;
353         final int abbrLength = endIndex - beginIndex;
354         if (abbrLength > allowedAbbreviationLength) {
355             final String abbr = str.substring(beginIndex, endIndex);
356             if (!allowedAbbreviations.contains(abbr)) {
357                 result = abbr;
358             }
359         }
360         return result;
361     }
362 
363     /**
364      * Gets all the children which are one level below on the current DetailAST
365      * parent node.
366      * @param node
367      *        Current parent node.
368      * @return The list of children one level below on the current parent node.
369      */
370     private static List<DetailAST> getChildren(final DetailAST node) {
371         final List<DetailAST> result = new LinkedList<>();
372         DetailAST curNode = node.getFirstChild();
373         while (curNode != null) {
374             result.add(curNode);
375             curNode = curNode.getNextSibling();
376         }
377         return result;
378     }
379 
380 }