commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles <gil...@harfang.homelinux.org>
Subject Re: [Math] Conventions
Date Sun, 20 Oct 2013 21:34:40 GMT
On Sun, 20 Oct 2013 22:15:18 +0200, Thomas Neidhart wrote:
> On 10/20/2013 09:56 PM, Gilles wrote:
>> 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).
>
> First you start the discussion like that:
>
>>>> 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.
>
> there is a convention (Oracle javadoc guide, which I like a lot and 
> try
> to follow), and there are several people who prefer using it 
> (especially
> when working on multiple projects -> javadoc hell).
>
> But you don't like this one, refuse to accept it as a convention and
> want to impose your own way of writing javadoc on others.

You quoted what I wrote; I mean what I wrote, and not your 
interpretation
of it.

The so-called "Oracle guidelines" are not a convention. IMO, a 
_project_
(not me!) can impose one choice among the many Oracle's suggestions.

> Based on such discussion, it will always be hard to impossible to 
> reach
> consensus, unless somebody gives way. And from my own experience, it
> does not hurt to give way yourself from time to time ... ;-)

I'll give way; let's continue to writing the Javadoc in the way we 
"like".

I'm sorry I raised such an issue once more. At least, I realize that 
what
you mean by "consensus" is a only a matter of finding people who agree 
on
what they like.
Do you like writing documentation? I don't; yet I know that it is 
useful...


Regards,
Gilles


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message