1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2024 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;
21
22 import java.util.Arrays;
23 import java.util.regex.Pattern;
24
25 import com.puppycrawl.tools.checkstyle.StatelessCheck;
26 import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
27 import com.puppycrawl.tools.checkstyle.api.DetailAST;
28 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
29 import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
30 import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
31
32 /**
33 * <p>
34 * The check to ensure that lines with code do not end with comment.
35 * For the case of {@code //} comments that means that the only thing that should precede
36 * it is whitespace. It doesn't check comments if they do not end a line; for example,
37 * it accepts the following: <code>Thread.sleep( 10 /*some comment here*/ );</code>
38 * Format property is intended to deal with the <code>} // while</code> example.
39 * </p>
40 * <p>
41 * Rationale: Steve McConnell in <cite>Code Complete</cite> suggests that endline
42 * comments are a bad practice. An end line comment would be one that is on
43 * the same line as actual code. For example:
44 * </p>
45 * <pre>
46 * a = b + c; // Some insightful comment
47 * d = e / f; // Another comment for this line
48 * </pre>
49 * <p>
50 * Quoting <cite>Code Complete</cite> for the justification:
51 * </p>
52 * <ul>
53 * <li>
54 * "The comments have to be aligned so that they do not interfere with the visual
55 * structure of the code. If you don't align them neatly, they'll make your listing
56 * look like it's been through a washing machine."
57 * </li>
58 * <li>
59 * "Endline comments tend to be hard to format...It takes time to align them.
60 * Such time is not spent learning more about the code; it's dedicated solely
61 * to the tedious task of pressing the spacebar or tab key."
62 * </li>
63 * <li>
64 * "Endline comments are also hard to maintain. If the code on any line containing
65 * an endline comment grows, it bumps the comment farther out, and all the other
66 * endline comments will have to bumped out to match. Styles that are hard to
67 * maintain aren't maintained...."
68 * </li>
69 * <li>
70 * "Endline comments also tend to be cryptic. The right side of the line doesn't
71 * offer much room and the desire to keep the comment on one line means the comment
72 * must be short. Work then goes into making the line as short as possible instead
73 * of as clear as possible. The comment usually ends up as cryptic as possible...."
74 * </li>
75 * <li>
76 * "A systemic problem with endline comments is that it's hard to write a meaningful
77 * comment for one line of code. Most endline comments just repeat the line of code,
78 * which hurts more than it helps."
79 * </li>
80 * </ul>
81 * <p>
82 * McConnell's comments on being hard to maintain when the size of the line changes
83 * are even more important in the age of automated refactorings.
84 * </p>
85 * <ul>
86 * <li>
87 * Property {@code format} - Specify pattern for strings allowed before the comment.
88 * Type is {@code java.util.regex.Pattern}.
89 * Default value is <code>"^[\s});]*$"</code>.
90 * </li>
91 * <li>
92 * Property {@code legalComment} - Define pattern for text allowed in trailing comments.
93 * This pattern will not be applied to multiline comments.
94 * Type is {@code java.util.regex.Pattern}.
95 * Default value is {@code null}.
96 * </li>
97 * </ul>
98 * <p>
99 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
100 * </p>
101 * <p>
102 * Violation Message Keys:
103 * </p>
104 * <ul>
105 * <li>
106 * {@code trailing.comments}
107 * </li>
108 * </ul>
109 *
110 * @noinspection HtmlTagCanBeJavadocTag
111 * @noinspectionreason HtmlTagCanBeJavadocTag - encoded symbols were not decoded
112 * when replaced with Javadoc tag
113 * @since 3.4
114 */
115 @StatelessCheck
116 public class TrailingCommentCheck extends AbstractCheck {
117
118 /**
119 * A key is pointing to the warning message text in "messages.properties"
120 * file.
121 */
122 public static final String MSG_KEY = "trailing.comments";
123
124 /** Specify pattern for strings to be formatted without comment specifiers. */
125 private static final Pattern FORMAT_LINE = Pattern.compile("/");
126
127 /**
128 * Define pattern for text allowed in trailing comments.
129 * This pattern will not be applied to multiline comments.
130 */
131 private Pattern legalComment;
132
133 /** Specify pattern for strings allowed before the comment. */
134 private Pattern format = Pattern.compile("^[\\s});]*$");
135
136 /**
137 * Setter to define pattern for text allowed in trailing comments.
138 * This pattern will not be applied to multiline comments.
139 *
140 * @param legalComment pattern to set.
141 * @since 4.2
142 */
143 public void setLegalComment(final Pattern legalComment) {
144 this.legalComment = legalComment;
145 }
146
147 /**
148 * Setter to specify pattern for strings allowed before the comment.
149 *
150 * @param pattern a pattern
151 * @since 3.4
152 */
153 public final void setFormat(Pattern pattern) {
154 format = pattern;
155 }
156
157 @Override
158 public boolean isCommentNodesRequired() {
159 return true;
160 }
161
162 @Override
163 public int[] getDefaultTokens() {
164 return getRequiredTokens();
165 }
166
167 @Override
168 public int[] getAcceptableTokens() {
169 return getRequiredTokens();
170 }
171
172 @Override
173 public int[] getRequiredTokens() {
174 return new int[] {
175 TokenTypes.SINGLE_LINE_COMMENT,
176 TokenTypes.BLOCK_COMMENT_BEGIN,
177 };
178 }
179
180 @Override
181 public void visitToken(DetailAST ast) {
182 if (ast.getType() == TokenTypes.SINGLE_LINE_COMMENT) {
183 checkSingleLineComment(ast);
184 }
185 else {
186 checkBlockComment(ast);
187 }
188 }
189
190 /**
191 * Checks if single-line comment is legal.
192 *
193 * @param ast Detail ast element to be checked.
194 */
195 private void checkSingleLineComment(DetailAST ast) {
196 final int lineNo = ast.getLineNo();
197 final String comment = ast.getFirstChild().getText();
198 final int[] lineBeforeCodePoints =
199 Arrays.copyOfRange(getLineCodePoints(lineNo - 1), 0, ast.getColumnNo());
200 final String lineBefore = new String(lineBeforeCodePoints, 0, lineBeforeCodePoints.length);
201
202 if (!format.matcher(lineBefore).find() && !isLegalCommentContent(comment)) {
203 log(ast, MSG_KEY);
204 }
205 }
206
207 /**
208 * Method to check if block comment is in correct format.
209 *
210 * @param ast Detail ast element to be checked.
211 */
212 private void checkBlockComment(DetailAST ast) {
213 final int lineNo = ast.getLineNo();
214 final DetailAST firstChild = ast.getFirstChild();
215 final DetailAST lastChild = ast.getLastChild();
216 final String comment = firstChild.getText();
217 int[] lineCodePoints = getLineCodePoints(lineNo - 1);
218
219 if (lineCodePoints.length > lastChild.getColumnNo() + 1) {
220 lineCodePoints = Arrays.copyOfRange(lineCodePoints,
221 lastChild.getColumnNo() + 2, lineCodePoints.length);
222 }
223
224 String line = new String(lineCodePoints, 0, lineCodePoints.length);
225 line = FORMAT_LINE.matcher(line).replaceAll("");
226
227 final int[] lineBeforeCodePoints =
228 Arrays.copyOfRange(getLineCodePoints(lineNo - 1), 0, ast.getColumnNo());
229 final String lineBefore = new String(lineBeforeCodePoints, 0, lineBeforeCodePoints.length);
230 final boolean isCommentAtEndOfLine = ast.getLineNo() != lastChild.getLineNo()
231 || CommonUtil.isBlank(line);
232 final boolean isLegalBlockComment = isLegalCommentContent(comment)
233 && TokenUtil.areOnSameLine(firstChild, lastChild)
234 || format.matcher(lineBefore).find();
235
236 if (isCommentAtEndOfLine && !isLegalBlockComment) {
237 log(ast, MSG_KEY);
238 }
239 }
240
241 /**
242 * Checks if given comment content is legal.
243 *
244 * @param commentContent comment content to check.
245 * @return true if the content is legal.
246 */
247 private boolean isLegalCommentContent(String commentContent) {
248 return legalComment != null && legalComment.matcher(commentContent).find();
249 }
250 }