Source code

001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2024 the original author or authors.
004//
005// This library is free software; you can redistribute it and/or
006// modify it under the terms of the GNU Lesser General Public
007// License as published by the Free Software Foundation; either
008// version 2.1 of the License, or (at your option) any later version.
009//
010// This library is distributed in the hope that it will be useful,
011// but WITHOUT ANY WARRANTY; without even the implied warranty of
012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013// Lesser General Public License for more details.
014//
015// You should have received a copy of the GNU Lesser General Public
016// License along with this library; if not, write to the Free Software
017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
018///////////////////////////////////////////////////////////////////////////////////////////////
019
020package com.puppycrawl.tools.checkstyle.checks;
021
022import java.util.Arrays;
023import java.util.regex.Pattern;
024
025import com.puppycrawl.tools.checkstyle.StatelessCheck;
026import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
027import com.puppycrawl.tools.checkstyle.api.DetailAST;
028import com.puppycrawl.tools.checkstyle.api.TokenTypes;
029import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
030import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
031
032/**
033 * <div>
034 * The check to ensure that lines with code do not end with comment.
035 * For the case of {@code //} comments that means that the only thing that should precede
036 * it is whitespace. It doesn't check comments if they do not end a line; for example,
037 * it accepts the following: <code>Thread.sleep( 10 /*some comment here&#42;/ );</code>
038 * Format property is intended to deal with the <code>} // while</code> example.
039 * </div>
040 *
041 * <p>
042 * Rationale: Steve McConnell in <cite>Code Complete</cite> suggests that endline
043 * comments are a bad practice. An end line comment would be one that is on
044 * the same line as actual code. For example:
045 * </p>
046 * <pre>
047 * a = b + c;      // Some insightful comment
048 * d = e / f;        // Another comment for this line
049 * </pre>
050 *
051 * <p>
052 * Quoting <cite>Code Complete</cite> for the justification:
053 * </p>
054 * <ul>
055 * <li>
056 * "The comments have to be aligned so that they do not interfere with the visual
057 * structure of the code. If you don't align them neatly, they'll make your listing
058 * look like it's been through a washing machine."
059 * </li>
060 * <li>
061 * "Endline comments tend to be hard to format...It takes time to align them.
062 * Such time is not spent learning more about the code; it's dedicated solely
063 * to the tedious task of pressing the spacebar or tab key."
064 * </li>
065 * <li>
066 * "Endline comments are also hard to maintain. If the code on any line containing
067 * an endline comment grows, it bumps the comment farther out, and all the other
068 * endline comments will have to bumped out to match. Styles that are hard to
069 * maintain aren't maintained...."
070 * </li>
071 * <li>
072 * "Endline comments also tend to be cryptic. The right side of the line doesn't
073 * offer much room and the desire to keep the comment on one line means the comment
074 * must be short. Work then goes into making the line as short as possible instead
075 * of as clear as possible. The comment usually ends up as cryptic as possible...."
076 * </li>
077 * <li>
078 * "A systemic problem with endline comments is that it's hard to write a meaningful
079 * comment for one line of code. Most endline comments just repeat the line of code,
080 * which hurts more than it helps."
081 * </li>
082 * </ul>
083 *
084 * <p>
085 * McConnell's comments on being hard to maintain when the size of the line changes
086 * are even more important in the age of automated refactorings.
087 * </p>
088 * <ul>
089 * <li>
090 * Property {@code format} - Specify pattern for strings allowed before the comment.
091 * Type is {@code java.util.regex.Pattern}.
092 * Default value is <code>"^[\s});]*$"</code>.
093 * </li>
094 * <li>
095 * Property {@code legalComment} - Define pattern for text allowed in trailing comments.
096 * This pattern will not be applied to multiline comments.
097 * Type is {@code java.util.regex.Pattern}.
098 * Default value is {@code null}.
099 * </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
121public 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}