1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2025 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 * <div class="wrapper"><pre class="prettyprint"><code class="language-java">
47 * a = b + c; // Some insightful comment
48 * d = e / f; // Another comment for this line
49 * </code></pre></div>
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 *
89 * @since 3.4
90 * @noinspection HtmlTagCanBeJavadocTag
91 * @noinspectionreason HtmlTagCanBeJavadocTag - encoded symbols were not decoded
92 * when replaced with Javadoc tag
93 */
94 @StatelessCheck
95 public class TrailingCommentCheck extends AbstractCheck {
96
97 /**
98 * A key is pointing to the warning message text in "messages.properties"
99 * file.
100 */
101 public static final String MSG_KEY = "trailing.comments";
102
103 /** Specify pattern for strings to be formatted without comment specifiers. */
104 private static final Pattern FORMAT_LINE = Pattern.compile("/");
105
106 /**
107 * Define pattern for text allowed in trailing comments.
108 * This pattern will not be applied to multiline comments.
109 */
110 private Pattern legalComment;
111
112 /** Specify pattern for strings allowed before the comment. */
113 private Pattern format = Pattern.compile("^[\\s});]*$");
114
115 /**
116 * Setter to define pattern for text allowed in trailing comments.
117 * This pattern will not be applied to multiline comments.
118 *
119 * @param legalComment pattern to set.
120 * @since 4.2
121 */
122 public void setLegalComment(final Pattern legalComment) {
123 this.legalComment = legalComment;
124 }
125
126 /**
127 * Setter to specify pattern for strings allowed before the comment.
128 *
129 * @param pattern a pattern
130 * @since 3.4
131 */
132 public final void setFormat(Pattern pattern) {
133 format = pattern;
134 }
135
136 @Override
137 public boolean isCommentNodesRequired() {
138 return true;
139 }
140
141 @Override
142 public int[] getDefaultTokens() {
143 return getRequiredTokens();
144 }
145
146 @Override
147 public int[] getAcceptableTokens() {
148 return getRequiredTokens();
149 }
150
151 @Override
152 public int[] getRequiredTokens() {
153 return new int[] {
154 TokenTypes.SINGLE_LINE_COMMENT,
155 TokenTypes.BLOCK_COMMENT_BEGIN,
156 };
157 }
158
159 @Override
160 public void visitToken(DetailAST ast) {
161 if (ast.getType() == TokenTypes.SINGLE_LINE_COMMENT) {
162 checkSingleLineComment(ast);
163 }
164 else {
165 checkBlockComment(ast);
166 }
167 }
168
169 /**
170 * Checks if single-line comment is legal.
171 *
172 * @param ast Detail ast element to be checked.
173 */
174 private void checkSingleLineComment(DetailAST ast) {
175 final int lineNo = ast.getLineNo();
176 final String comment = ast.getFirstChild().getText();
177 final int[] lineBeforeCodePoints =
178 Arrays.copyOfRange(getLineCodePoints(lineNo - 1), 0, ast.getColumnNo());
179 final String lineBefore = new String(lineBeforeCodePoints, 0, lineBeforeCodePoints.length);
180
181 if (!format.matcher(lineBefore).find() && !isLegalCommentContent(comment)) {
182 log(ast, MSG_KEY);
183 }
184 }
185
186 /**
187 * Method to check if block comment is in correct format.
188 *
189 * @param ast Detail ast element to be checked.
190 */
191 private void checkBlockComment(DetailAST ast) {
192 final int lineNo = ast.getLineNo();
193 final DetailAST firstChild = ast.getFirstChild();
194 final DetailAST lastChild = ast.getLastChild();
195 final String comment = firstChild.getText();
196 int[] lineCodePoints = getLineCodePoints(lineNo - 1);
197
198 if (lineCodePoints.length > lastChild.getColumnNo() + 1) {
199 lineCodePoints = Arrays.copyOfRange(lineCodePoints,
200 lastChild.getColumnNo() + 2, lineCodePoints.length);
201 }
202
203 String line = new String(lineCodePoints, 0, lineCodePoints.length);
204 line = FORMAT_LINE.matcher(line).replaceAll("");
205
206 final int[] lineBeforeCodePoints =
207 Arrays.copyOfRange(getLineCodePoints(lineNo - 1), 0, ast.getColumnNo());
208 final String lineBefore = new String(lineBeforeCodePoints, 0, lineBeforeCodePoints.length);
209 final boolean isCommentAtEndOfLine = ast.getLineNo() != lastChild.getLineNo()
210 || CommonUtil.isBlank(line);
211 final boolean isLegalBlockComment = isLegalCommentContent(comment)
212 && TokenUtil.areOnSameLine(firstChild, lastChild)
213 || format.matcher(lineBefore).find();
214
215 if (isCommentAtEndOfLine && !isLegalBlockComment) {
216 log(ast, MSG_KEY);
217 }
218 }
219
220 /**
221 * Checks if given comment content is legal.
222 *
223 * @param commentContent comment content to check.
224 * @return true if the content is legal.
225 */
226 private boolean isLegalCommentContent(String commentContent) {
227 return legalComment != null && legalComment.matcher(commentContent).find();
228 }
229 }