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."
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.
Phil
[1]
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#format
>
>
> Regards,
> Gilles
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [email protected]
> For additional commands, e-mail: [email protected]
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
