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