On 3/25/15 2:39 PM, Laurent Bourgès wrote:
Also, the very first file I brought up still had /** */ single line faux-doc
comments (AAShapePipe, on private fields no less). That was the second thing
you said that you fixed below...?
I disagree: this is a typical javadoc comment for a field (even
private). Maybe you dislike javadoc for fields.
What's clearly the problem ? Do you want me to remove all new comments /
javadoc ?
I absolutely do not want you to delete the comments. The content of the
comments are important.
This is a minor style note and there is no functional flaw, but use of
the "/**" format for these comments is inappropriate and out of place
for internal code like this. "/**" implies:
- we are going to run javadoc on this code (we aren't)
- the output of javadoc will be published somewhere (it won't)
- the comment adheres to much higher standards of content, including:
- use of full sentences (most if all of these are sentence fragments)
- use of recommended grammar and verb tenses as per the doc writer
guidelines
- proper annotations like @since and @see where appropriate
- does the text of the comment promise something we don't want to
guarantee?
- does the text of the comment mention specific caveats we need to
communicate?
You may believe that these are "typical javadoc comments for a field",
but "/** dirty aabox array */" would never pass muster if we were
planning on actually publishing these comments.
It's like talking to one of your siblings in a casual setting and yet
using their full formal name and title. There's nothing wrong with it,
but it takes one out of the context and for just a second they wonder
"are they about to reprimand me? Oh, no, they're just being oddly
formal..."
I would just use the "//" notation for these comments...
...jim
