On Sun, 20 Oct 2013 12:09:44 -0700, Phil Steitz wrote:
On 10/20/13 10:44 AM, Gilles wrote:
Hi.
[...]
I notice that you changed back the uppercasing of the "@param"
Javadoc. I've a personal preference for having an uppercase letter
there, but I'd like that we fix the _project's_ preference. I
think that is important to have rules (yes, even trivial ones)
so that people (both committers and new contributors) can
unequivocally know what is expected in as many areas as possible.
This will reduce the amount of work for everyone.
[Sorry for the little hijacking of this thread.]
Unfortunately, I do not agree with that convention. It is not
standard and most of the code (including the rest of the class)
follows the standard convention (see the Oracle / Sun docs).
I'm fine with whatever we have to follow, but this should be fixed
once and for all, to avoid any spurious change that happens to suit
one's preferences.
We can follow what is used in most of the JDK docs. Let's just say
that it is what we do, and then let's do it: the class here does not
do that; if it were, a comment like "number of successes" would
rather be "the number of observed successes" (i.e. using the word
"the" and with emphasis on repeating "observed" so that the comment
is not just the parameter name with spaces).
I know that this sounds trivial; the problem is that everybody can
come up with good reasons for what he is used to do. When someone
contributes to a project, there are things that must be done
because... it is so. Fixing trivial rules has good consequences
since even new contributors can easily follow those rules.
It will short-circuit a certain amount of discussion and less work
for reviewers/committers.
I suggest, once again, that we follow the Oracle conventions [1].
The relevant bit for this nit is
"Parameter names are lowercase by convention. The data type starts
with a lowercase letter to indicate an object rather than a class.
The description begins with a lowercase letter if it is a phrase
(contains no verb), or an uppercase letter if it is a sentence. End
the phrase with a period only if another phrase or sentence follows
it.
Example:
* @param ch the character to be tested
* @param observer the image observer to be notified
...
When writing the comments themselves, in general, start with a
phrase and follow it with sentences if they are needed.
*
When writing a phrase, do not capitalize and do not end with a
period:
@param x the x-coordinate, measured in pixels
*
When writing a phrase followed by a sentence, do not capitalize
the phrase, but end it with a period to distinguish it from the
start of the next sentence:
@param x the x-coordinate. Measured in pixels.
*
If you prefer starting with a sentence, capitalize it and end it
with a period:
@param x Specifies the x-coordinate, measured in pixels.
*
When writing multiple sentences, follow normal sentence rules:
@param x Specifies the x-coordinate. Measured in pixels."
IMHO, this shows that there is really no standardization. E.g. what I
proposed in a previous discussion on this subject is also quite close
to an "Oracle rule", namely,
If you prefer starting with a sentence, capitalize it and end it
with a period.
And particularly
When writing multiple sentences, follow normal sentence rules.
Which I would in effect _simplify_ further as simply: Follow normal
sentence rules.
I prefer to keep things as brief as possible. That means @param is
generally a short phrase describing the parameter and rarely a full
sentence. Adding "the" in front is OK but not necessary, IMO and I
would like to keep the content and formatting rules as simple and
non-restrictive as possible. I disagree with the statement that
more rules means less work. It is actually the opposite. Fewer
hard rules means less work both for contributors and committers. I
would much rather have us focus on the *meaning* and *comprehension*
of the javadoc than nits about formatting.
This is exactly what I postulated: I can explain my preferences, you
can explain yours, and we won't have a standardized source code.
Less rules means less work for oneself, and more work for the others
(the project's team).
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
