-
Notifications
You must be signed in to change notification settings - Fork 13.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
java: javadoc: Consider clarifying “containing only the aligned leading asterisk” #820
Comments
the intent is to not have trailing whitespace. many editors & formatters will flag & delete it automatically. |
In Google's internal version of this style guide, there is a section on issues that do not deserve to be commented on in code reviews. Trailing whitespace is the very first one. So I think we could consider that the intent is that there really is just an asterisk with no following space, but if there is following space then that is not worth commenting about. The internal guide does also say "It is reasonable to ask the reviewee to check their editor configuration, but don't point out specific violations." (Referring to this and also things like whether there is a newline at the end of the last line.) I have to say that I'm not really convinced by the argument that a space after the asterisk is useful because you might conceivably be adding new comment text there. It isn't hard to type a space when you need one. |
About Javadoc, the GJSG states: “One blank line—that is, a line containing only the aligned leading asterisk (*)—appears between paragraphs, and before the group of block tags if present.”
Is the intent to prohibit a space after the asterisk? I thought not as the space does not hurt visually and is useful (as reported here), but others interpret this differently.
Please consider clarifying, for example by rewording to “a line containing only the aligned leading asterisk (*) optionally followed by a single space character”, if this is the intent.
The text was updated successfully, but these errors were encountered: