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